fix(clerk-js): Add nonce to captcha script element

.changeset/witty-parks-attack.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Adds Content Security Policy (CSP) nonce support to the Cloudflare Turnstile

packages/clerk-js/src/utils/__tests__/captcha.spec.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { shouldRetryTurnstileErrorCode } from '../captcha/turnstile';
+import type { CaptchaOptions } from '../captcha/types';
 
 describe('shouldRetryTurnstileErrorCode', () => {
  it.each([
@@ -23,3 +24,229 @@ describe('shouldRetryTurnstileErrorCode', () => {
  expect(shouldRetryTurnstileErrorCode(str)).toBe(expected);
  });
 });
+
+describe('Nonce support', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.resetModules();
+ });
+
+ describe('retrieveCaptchaInfo', () => {
+ it('should extract nonce from clerk options when available', async () => {
+ // Mock clerk instance with internal options
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('test-nonce-123'),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(mockClerk.__internal_getOption).toHaveBeenCalledWith('nonce');
+ expect(result.nonce).toBe('test-nonce-123');
+ expect(result.captchaSiteKey).toBe('test-site-key');
+ expect(result.captchaProvider).toBe('turnstile');
+ });
+
+ it('should return undefined nonce when not available in clerk options', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+
+ it('should handle clerk instance without __internal_getOption method', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ // No __internal_getOption method
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaOptions type support', () => {
+ it('should accept nonce in CaptchaOptions type definition', () => {
+ // This test verifies that the CaptchaOptions type includes the nonce field
+ const validOptions: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ closeModal: async () => {},
+ invisibleSiteKey: 'test-invisible-key',
+ modalContainerQuerySelector: '.modal',
+ modalWrapperQuerySelector: '.wrapper',
+ nonce: 'test-nonce-from-csp',
+ openModal: async () => {},
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ };
+
+ // If this compiles without TypeScript errors, the test passes
+ expect(validOptions.nonce).toBe('test-nonce-from-csp');
+ });
+
+ it('should allow undefined nonce in CaptchaOptions', () => {
+ const validOptionsWithoutNonce: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ invisibleSiteKey: 'test-invisible-key',
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ // nonce is optional
+ };
+
+ expect(validOptionsWithoutNonce.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaChallenge nonce integration', () => {
+ let mockClerk: any;
+
+ beforeEach(async () => {
+ // Mock clerk instance
+ mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('clerk-nonce-789'),
+ };
+
+ // Mock getCaptchaToken
+ vi.doMock('../captcha/getCaptchaToken', () => ({
+ getCaptchaToken: vi.fn().mockResolvedValue({
+ captchaToken: 'mock-token',
+ captchaWidgetType: 'invisible',
+ }),
+ }));
+ });
+
+ it('should use nonce from clerk options in invisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-invisible-key',
+ widgetType: 'invisible',
+ }),
+ );
+ });
+
+ it('should use nonce from clerk options in managedOrInvisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.managedOrInvisible({ action: 'verify' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-site-key',
+ widgetType: 'managed',
+ }),
+ );
+ });
+
+ it('should prefer explicit nonce over clerk options nonce', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({
+ action: 'signup',
+ nonce: 'explicit-nonce-override',
+ });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'explicit-nonce-override',
+ }),
+ );
+ });
+
+ it('should handle missing nonce gracefully', async () => {
+ // Mock clerk without nonce
+ const clerkWithoutNonce = {
+ ...mockClerk,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(clerkWithoutNonce);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: undefined,
+ }),
+ );
+ });
+ });
+});

packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts

@@ -12,15 +12,16 @@ export class CaptchaChallenge {
  * always use the fallback key.
  */
  public async invisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible } = retrieveCaptchaInfo(this.clerk);
+ const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible, nonce } = retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
- siteKey: captchaPublicKeyInvisible,
+ action: opts?.action,
+ captchaProvider: 'turnstile',
  invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: opts?.nonce || nonce || undefined,
+ siteKey: captchaPublicKeyInvisible,
  widgetType: 'invisible',
- captchaProvider: 'turnstile',
- action: opts?.action,
  }).catch(e => {
  if (e.captchaError) {
  return { captchaError: e.captchaError };
@@ -42,15 +43,16 @@ export class CaptchaChallenge {
  * Managed challenged start as non-interactive and escalate to interactive if necessary.
  */
  public async managedOrInvisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible } =
+ const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible, nonce } =
  retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
+ captchaProvider,
+ invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: nonce || undefined,
  siteKey: captchaSiteKey,
  widgetType: captchaWidgetType,
- invisibleSiteKey: captchaPublicKeyInvisible,
- captchaProvider,
  ...opts,
  }).catch(e => {
  if (e.captchaError) {

packages/clerk-js/src/utils/captcha/retrieveCaptchaInfo.ts

@@ -4,11 +4,15 @@ export const retrieveCaptchaInfo = (clerk: Clerk) => {
  const _environment = clerk.__unstable__environment;
  const captchaProvider = _environment ? _environment.displayConfig.captchaProvider : 'turnstile';
 
+ // Access nonce via internal options - casting to any since nonce is in IsomorphicClerkOptions but not ClerkOptions
+ const nonce = (clerk as any).__internal_getOption?.('nonce') as string | undefined;
+
  return {
  captchaSiteKey: _environment ? _environment.displayConfig.captchaPublicKey : null,
  captchaWidgetType: _environment ? _environment.displayConfig.captchaWidgetType : null,
  captchaProvider,
  captchaPublicKeyInvisible: _environment ? _environment.displayConfig.captchaPublicKeyInvisible : null,
  canUseCaptcha: _environment ? _environment.userSettings.signUp.captcha_enabled && clerk.isStandardBrowser : null,
+ nonce: nonce || undefined,
  };
 };

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -26,23 +26,23 @@ export const shouldRetryTurnstileErrorCode = (errorCode: string) => {
  return !!codesWithRetries.find(w => errorCode.startsWith(w));
 };
 
-async function loadCaptcha() {
+async function loadCaptcha(nonce?: string) {
  if (!window.turnstile) {
- await loadCaptchaFromCloudflareURL().catch(() => {
+ await loadCaptchaFromCloudflareURL(nonce).catch(() => {
  // eslint-disable-next-line @typescript-eslint/only-throw-error
  throw { captchaError: 'captcha_script_failed_to_load' };
  });
  }
  return window.turnstile;
 }
 
-async function loadCaptchaFromCloudflareURL() {
+async function loadCaptchaFromCloudflareURL(nonce?: string) {
  try {
  if (__BUILD_DISABLE_RHC__) {
  return Promise.reject(new Error('Captcha not supported in this environment'));
  }
 
- return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true });
+ return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true, nonce });
  } catch (err) {
  console.warn(
  'Clerk: Failed to load the CAPTCHA script from Cloudflare. If you see a CSP error in your browser, please add the necessary CSP rules to your app. Visit https://clerk.com/docs/security/clerk-csp for more information.',
@@ -71,9 +71,9 @@ function getCaptchaAttibutesFromElemenet(element: HTMLElement): CaptchaAttribute
  * not exist, the invisibleSiteKey is used as a fallback and the widget is rendered in a hidden div at the bottom of the body.
  */
 export const getTurnstileToken = async (opts: CaptchaOptions) => {
- const { siteKey, widgetType, invisibleSiteKey } = opts;
+ const { siteKey, widgetType, invisibleSiteKey, nonce } = opts;
  const { modalContainerQuerySelector, modalWrapperQuerySelector, closeModal, openModal } = opts;
- const captcha: Turnstile.Turnstile = await loadCaptcha();
+ const captcha: Turnstile.Turnstile = await loadCaptcha(nonce);
  const errorCodes: (string | number)[] = [];
 
  let captchaToken = '';

packages/clerk-js/src/utils/captcha/types.ts

@@ -1,15 +1,16 @@
 import type { CaptchaProvider, CaptchaWidgetType } from '@clerk/types';
 
 export type CaptchaOptions = {
- siteKey: string;
- widgetType: CaptchaWidgetType;
- invisibleSiteKey: string;
+ action?: 'verify' | 'signup' | 'heartbeat';
  captchaProvider: CaptchaProvider;
+ closeModal?: () => Promise<unknown>;
+ invisibleSiteKey: string;
  modalContainerQuerySelector?: string;
  modalWrapperQuerySelector?: string;
+ nonce?: string;
  openModal?: () => Promise<unknown>;
-closeModal?: () => Promise<unknown>;
-action?: 'verify' | 'signup' | 'heartbeat';
+siteKey: string;
+widgetType: CaptchaWidgetType;
 };
 
 export type GetCaptchaTokenReturn = {

.changeset/witty-parks-attack.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Adds Content Security Policy (CSP) nonce support to the Cloudflare Turnstile

packages/clerk-js/src/utils/__tests__/captcha.spec.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { shouldRetryTurnstileErrorCode } from '../captcha/turnstile';
+import type { CaptchaOptions } from '../captcha/types';
 
 describe('shouldRetryTurnstileErrorCode', () => {
  it.each([
@@ -23,3 +24,229 @@ describe('shouldRetryTurnstileErrorCode', () => {
  expect(shouldRetryTurnstileErrorCode(str)).toBe(expected);
  });
 });
+
+describe('Nonce support', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.resetModules();
+ });
+
+ describe('retrieveCaptchaInfo', () => {
+ it('should extract nonce from clerk options when available', async () => {
+ // Mock clerk instance with internal options
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('test-nonce-123'),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(mockClerk.__internal_getOption).toHaveBeenCalledWith('nonce');
+ expect(result.nonce).toBe('test-nonce-123');
+ expect(result.captchaSiteKey).toBe('test-site-key');
+ expect(result.captchaProvider).toBe('turnstile');
+ });
+
+ it('should return undefined nonce when not available in clerk options', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+
+ it('should handle clerk instance without __internal_getOption method', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ // No __internal_getOption method
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaOptions type support', () => {
+ it('should accept nonce in CaptchaOptions type definition', () => {
+ // This test verifies that the CaptchaOptions type includes the nonce field
+ const validOptions: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ closeModal: async () => {},
+ invisibleSiteKey: 'test-invisible-key',
+ modalContainerQuerySelector: '.modal',
+ modalWrapperQuerySelector: '.wrapper',
+ nonce: 'test-nonce-from-csp',
+ openModal: async () => {},
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ };
+
+ // If this compiles without TypeScript errors, the test passes
+ expect(validOptions.nonce).toBe('test-nonce-from-csp');
+ });
+
+ it('should allow undefined nonce in CaptchaOptions', () => {
+ const validOptionsWithoutNonce: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ invisibleSiteKey: 'test-invisible-key',
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ // nonce is optional
+ };
+
+ expect(validOptionsWithoutNonce.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaChallenge nonce integration', () => {
+ let mockClerk: any;
+
+ beforeEach(async () => {
+ // Mock clerk instance
+ mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('clerk-nonce-789'),
+ };
+
+ // Mock getCaptchaToken
+ vi.doMock('../captcha/getCaptchaToken', () => ({
+ getCaptchaToken: vi.fn().mockResolvedValue({
+ captchaToken: 'mock-token',
+ captchaWidgetType: 'invisible',
+ }),
+ }));
+ });
+
+ it('should use nonce from clerk options in invisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-invisible-key',
+ widgetType: 'invisible',
+ }),
+ );
+ });
+
+ it('should use nonce from clerk options in managedOrInvisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.managedOrInvisible({ action: 'verify' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-site-key',
+ widgetType: 'managed',
+ }),
+ );
+ });
+
+ it('should prefer explicit nonce over clerk options nonce', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({
+ action: 'signup',
+ nonce: 'explicit-nonce-override',
+ });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'explicit-nonce-override',
+ }),
+ );
+ });
+
+ it('should handle missing nonce gracefully', async () => {
+ // Mock clerk without nonce
+ const clerkWithoutNonce = {
+ ...mockClerk,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(clerkWithoutNonce);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: undefined,
+ }),
+ );
+ });
+ });
+});

packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts

@@ -12,15 +12,16 @@ export class CaptchaChallenge {
  * always use the fallback key.
  */
  public async invisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible } = retrieveCaptchaInfo(this.clerk);
+ const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible, nonce } = retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
- siteKey: captchaPublicKeyInvisible,
+ action: opts?.action,
+ captchaProvider: 'turnstile',
  invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: opts?.nonce || nonce || undefined,
+ siteKey: captchaPublicKeyInvisible,
  widgetType: 'invisible',
- captchaProvider: 'turnstile',
- action: opts?.action,
  }).catch(e => {
  if (e.captchaError) {
  return { captchaError: e.captchaError };
@@ -42,15 +43,16 @@ export class CaptchaChallenge {
  * Managed challenged start as non-interactive and escalate to interactive if necessary.
  */
  public async managedOrInvisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible } =
+ const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible, nonce } =
  retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
+ captchaProvider,
+ invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: nonce || undefined,
  siteKey: captchaSiteKey,
  widgetType: captchaWidgetType,
- invisibleSiteKey: captchaPublicKeyInvisible,
- captchaProvider,
  ...opts,
  }).catch(e => {
  if (e.captchaError) {

packages/clerk-js/src/utils/captcha/retrieveCaptchaInfo.ts

@@ -4,11 +4,15 @@ export const retrieveCaptchaInfo = (clerk: Clerk) => {
  const _environment = clerk.__unstable__environment;
  const captchaProvider = _environment ? _environment.displayConfig.captchaProvider : 'turnstile';
 
+ // Access nonce via internal options - casting to any since nonce is in IsomorphicClerkOptions but not ClerkOptions
+ const nonce = (clerk as any).__internal_getOption?.('nonce') as string | undefined;
+
  return {
  captchaSiteKey: _environment ? _environment.displayConfig.captchaPublicKey : null,
  captchaWidgetType: _environment ? _environment.displayConfig.captchaWidgetType : null,
  captchaProvider,
  captchaPublicKeyInvisible: _environment ? _environment.displayConfig.captchaPublicKeyInvisible : null,
  canUseCaptcha: _environment ? _environment.userSettings.signUp.captcha_enabled && clerk.isStandardBrowser : null,
+ nonce: nonce || undefined,
  };
 };

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -26,23 +26,23 @@ export const shouldRetryTurnstileErrorCode = (errorCode: string) => {
  return !!codesWithRetries.find(w => errorCode.startsWith(w));
 };
 
-async function loadCaptcha() {
+async function loadCaptcha(nonce?: string) {
  if (!window.turnstile) {
- await loadCaptchaFromCloudflareURL().catch(() => {
+ await loadCaptchaFromCloudflareURL(nonce).catch(() => {
  // eslint-disable-next-line @typescript-eslint/only-throw-error
  throw { captchaError: 'captcha_script_failed_to_load' };
  });
  }
  return window.turnstile;
 }
 
-async function loadCaptchaFromCloudflareURL() {
+async function loadCaptchaFromCloudflareURL(nonce?: string) {
  try {
  if (__BUILD_DISABLE_RHC__) {
  return Promise.reject(new Error('Captcha not supported in this environment'));
  }
 
- return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true });
+ return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true, nonce });
  } catch (err) {
  console.warn(
  'Clerk: Failed to load the CAPTCHA script from Cloudflare. If you see a CSP error in your browser, please add the necessary CSP rules to your app. Visit https://clerk.com/docs/security/clerk-csp for more information.',
@@ -71,9 +71,9 @@ function getCaptchaAttibutesFromElemenet(element: HTMLElement): CaptchaAttribute
  * not exist, the invisibleSiteKey is used as a fallback and the widget is rendered in a hidden div at the bottom of the body.
  */
 export const getTurnstileToken = async (opts: CaptchaOptions) => {
- const { siteKey, widgetType, invisibleSiteKey } = opts;
+ const { siteKey, widgetType, invisibleSiteKey, nonce } = opts;
  const { modalContainerQuerySelector, modalWrapperQuerySelector, closeModal, openModal } = opts;
- const captcha: Turnstile.Turnstile = await loadCaptcha();
+ const captcha: Turnstile.Turnstile = await loadCaptcha(nonce);
  const errorCodes: (string | number)[] = [];
 
  let captchaToken = '';

packages/clerk-js/src/utils/captcha/types.ts

@@ -1,15 +1,16 @@
 import type { CaptchaProvider, CaptchaWidgetType } from '@clerk/types';
 
 export type CaptchaOptions = {
- siteKey: string;
- widgetType: CaptchaWidgetType;
- invisibleSiteKey: string;
+ action?: 'verify' | 'signup' | 'heartbeat';
  captchaProvider: CaptchaProvider;
+ closeModal?: () => Promise<unknown>;
+ invisibleSiteKey: string;
  modalContainerQuerySelector?: string;
  modalWrapperQuerySelector?: string;
+ nonce?: string;
  openModal?: () => Promise<unknown>;
-closeModal?: () => Promise<unknown>;
-action?: 'verify' | 'signup' | 'heartbeat';
+siteKey: string;
+widgetType: CaptchaWidgetType;
 };
 
 export type GetCaptchaTokenReturn = {

.changeset/witty-parks-attack.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Adds Content Security Policy (CSP) nonce support to the Cloudflare Turnstile

packages/clerk-js/src/utils/__tests__/captcha.spec.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { shouldRetryTurnstileErrorCode } from '../captcha/turnstile';
+import type { CaptchaOptions } from '../captcha/types';
 
 describe('shouldRetryTurnstileErrorCode', () => {
  it.each([
@@ -23,3 +24,229 @@ describe('shouldRetryTurnstileErrorCode', () => {
  expect(shouldRetryTurnstileErrorCode(str)).toBe(expected);
  });
 });
+
+describe('Nonce support', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.resetModules();
+ });
+
+ describe('retrieveCaptchaInfo', () => {
+ it('should extract nonce from clerk options when available', async () => {
+ // Mock clerk instance with internal options
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('test-nonce-123'),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(mockClerk.__internal_getOption).toHaveBeenCalledWith('nonce');
+ expect(result.nonce).toBe('test-nonce-123');
+ expect(result.captchaSiteKey).toBe('test-site-key');
+ expect(result.captchaProvider).toBe('turnstile');
+ });
+
+ it('should return undefined nonce when not available in clerk options', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+
+ it('should handle clerk instance without __internal_getOption method', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ // No __internal_getOption method
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaOptions type support', () => {
+ it('should accept nonce in CaptchaOptions type definition', () => {
+ // This test verifies that the CaptchaOptions type includes the nonce field
+ const validOptions: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ closeModal: async () => {},
+ invisibleSiteKey: 'test-invisible-key',
+ modalContainerQuerySelector: '.modal',
+ modalWrapperQuerySelector: '.wrapper',
+ nonce: 'test-nonce-from-csp',
+ openModal: async () => {},
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ };
+
+ // If this compiles without TypeScript errors, the test passes
+ expect(validOptions.nonce).toBe('test-nonce-from-csp');
+ });
+
+ it('should allow undefined nonce in CaptchaOptions', () => {
+ const validOptionsWithoutNonce: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ invisibleSiteKey: 'test-invisible-key',
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ // nonce is optional
+ };
+
+ expect(validOptionsWithoutNonce.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaChallenge nonce integration', () => {
+ let mockClerk: any;
+
+ beforeEach(async () => {
+ // Mock clerk instance
+ mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('clerk-nonce-789'),
+ };
+
+ // Mock getCaptchaToken
+ vi.doMock('../captcha/getCaptchaToken', () => ({
+ getCaptchaToken: vi.fn().mockResolvedValue({
+ captchaToken: 'mock-token',
+ captchaWidgetType: 'invisible',
+ }),
+ }));
+ });
+
+ it('should use nonce from clerk options in invisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-invisible-key',
+ widgetType: 'invisible',
+ }),
+ );
+ });
+
+ it('should use nonce from clerk options in managedOrInvisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.managedOrInvisible({ action: 'verify' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-site-key',
+ widgetType: 'managed',
+ }),
+ );
+ });
+
+ it('should prefer explicit nonce over clerk options nonce', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({
+ action: 'signup',
+ nonce: 'explicit-nonce-override',
+ });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'explicit-nonce-override',
+ }),
+ );
+ });
+
+ it('should handle missing nonce gracefully', async () => {
+ // Mock clerk without nonce
+ const clerkWithoutNonce = {
+ ...mockClerk,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(clerkWithoutNonce);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: undefined,
+ }),
+ );
+ });
+ });
+});

packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts

@@ -12,15 +12,16 @@ export class CaptchaChallenge {
  * always use the fallback key.
  */
  public async invisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible } = retrieveCaptchaInfo(this.clerk);
+ const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible, nonce } = retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
- siteKey: captchaPublicKeyInvisible,
+ action: opts?.action,
+ captchaProvider: 'turnstile',
  invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: opts?.nonce || nonce || undefined,
+ siteKey: captchaPublicKeyInvisible,
  widgetType: 'invisible',
- captchaProvider: 'turnstile',
- action: opts?.action,
  }).catch(e => {
  if (e.captchaError) {
  return { captchaError: e.captchaError };
@@ -42,15 +43,16 @@ export class CaptchaChallenge {
  * Managed challenged start as non-interactive and escalate to interactive if necessary.
  */
  public async managedOrInvisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible } =
+ const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible, nonce } =
  retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
+ captchaProvider,
+ invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: nonce || undefined,
  siteKey: captchaSiteKey,
  widgetType: captchaWidgetType,
- invisibleSiteKey: captchaPublicKeyInvisible,
- captchaProvider,
  ...opts,
  }).catch(e => {
  if (e.captchaError) {

packages/clerk-js/src/utils/captcha/retrieveCaptchaInfo.ts

@@ -4,11 +4,15 @@ export const retrieveCaptchaInfo = (clerk: Clerk) => {
  const _environment = clerk.__unstable__environment;
  const captchaProvider = _environment ? _environment.displayConfig.captchaProvider : 'turnstile';
 
+ // Access nonce via internal options - casting to any since nonce is in IsomorphicClerkOptions but not ClerkOptions
+ const nonce = (clerk as any).__internal_getOption?.('nonce') as string | undefined;
+
  return {
  captchaSiteKey: _environment ? _environment.displayConfig.captchaPublicKey : null,
  captchaWidgetType: _environment ? _environment.displayConfig.captchaWidgetType : null,
  captchaProvider,
  captchaPublicKeyInvisible: _environment ? _environment.displayConfig.captchaPublicKeyInvisible : null,
  canUseCaptcha: _environment ? _environment.userSettings.signUp.captcha_enabled && clerk.isStandardBrowser : null,
+ nonce: nonce || undefined,
  };
 };

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -26,23 +26,23 @@ export const shouldRetryTurnstileErrorCode = (errorCode: string) => {
  return !!codesWithRetries.find(w => errorCode.startsWith(w));
 };
 
-async function loadCaptcha() {
+async function loadCaptcha(nonce?: string) {
  if (!window.turnstile) {
- await loadCaptchaFromCloudflareURL().catch(() => {
+ await loadCaptchaFromCloudflareURL(nonce).catch(() => {
  // eslint-disable-next-line @typescript-eslint/only-throw-error
  throw { captchaError: 'captcha_script_failed_to_load' };
  });
  }
  return window.turnstile;
 }
 
-async function loadCaptchaFromCloudflareURL() {
+async function loadCaptchaFromCloudflareURL(nonce?: string) {
  try {
  if (__BUILD_DISABLE_RHC__) {
  return Promise.reject(new Error('Captcha not supported in this environment'));
  }
 
- return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true });
+ return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true, nonce });
  } catch (err) {
  console.warn(
  'Clerk: Failed to load the CAPTCHA script from Cloudflare. If you see a CSP error in your browser, please add the necessary CSP rules to your app. Visit https://clerk.com/docs/security/clerk-csp for more information.',
@@ -71,9 +71,9 @@ function getCaptchaAttibutesFromElemenet(element: HTMLElement): CaptchaAttribute
  * not exist, the invisibleSiteKey is used as a fallback and the widget is rendered in a hidden div at the bottom of the body.
  */
 export const getTurnstileToken = async (opts: CaptchaOptions) => {
- const { siteKey, widgetType, invisibleSiteKey } = opts;
+ const { siteKey, widgetType, invisibleSiteKey, nonce } = opts;
  const { modalContainerQuerySelector, modalWrapperQuerySelector, closeModal, openModal } = opts;
- const captcha: Turnstile.Turnstile = await loadCaptcha();
+ const captcha: Turnstile.Turnstile = await loadCaptcha(nonce);
  const errorCodes: (string | number)[] = [];
 
  let captchaToken = '';

packages/clerk-js/src/utils/captcha/types.ts

@@ -1,15 +1,16 @@
 import type { CaptchaProvider, CaptchaWidgetType } from '@clerk/types';
 
 export type CaptchaOptions = {
- siteKey: string;
- widgetType: CaptchaWidgetType;
- invisibleSiteKey: string;
+ action?: 'verify' | 'signup' | 'heartbeat';
  captchaProvider: CaptchaProvider;
+ closeModal?: () => Promise<unknown>;
+ invisibleSiteKey: string;
  modalContainerQuerySelector?: string;
  modalWrapperQuerySelector?: string;
+ nonce?: string;
  openModal?: () => Promise<unknown>;
-closeModal?: () => Promise<unknown>;
-action?: 'verify' | 'signup' | 'heartbeat';
+siteKey: string;
+widgetType: CaptchaWidgetType;
 };
 
 export type GetCaptchaTokenReturn = {

.changeset/witty-parks-attack.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Adds Content Security Policy (CSP) nonce support to the Cloudflare Turnstile

packages/clerk-js/src/utils/__tests__/captcha.spec.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { shouldRetryTurnstileErrorCode } from '../captcha/turnstile';
+import type { CaptchaOptions } from '../captcha/types';
 
 describe('shouldRetryTurnstileErrorCode', () => {
  it.each([
@@ -23,3 +24,229 @@ describe('shouldRetryTurnstileErrorCode', () => {
  expect(shouldRetryTurnstileErrorCode(str)).toBe(expected);
  });
 });
+
+describe('Nonce support', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.resetModules();
+ });
+
+ describe('retrieveCaptchaInfo', () => {
+ it('should extract nonce from clerk options when available', async () => {
+ // Mock clerk instance with internal options
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('test-nonce-123'),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(mockClerk.__internal_getOption).toHaveBeenCalledWith('nonce');
+ expect(result.nonce).toBe('test-nonce-123');
+ expect(result.captchaSiteKey).toBe('test-site-key');
+ expect(result.captchaProvider).toBe('turnstile');
+ });
+
+ it('should return undefined nonce when not available in clerk options', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+
+ it('should handle clerk instance without __internal_getOption method', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ // No __internal_getOption method
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaOptions type support', () => {
+ it('should accept nonce in CaptchaOptions type definition', () => {
+ // This test verifies that the CaptchaOptions type includes the nonce field
+ const validOptions: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ closeModal: async () => {},
+ invisibleSiteKey: 'test-invisible-key',
+ modalContainerQuerySelector: '.modal',
+ modalWrapperQuerySelector: '.wrapper',
+ nonce: 'test-nonce-from-csp',
+ openModal: async () => {},
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ };
+
+ // If this compiles without TypeScript errors, the test passes
+ expect(validOptions.nonce).toBe('test-nonce-from-csp');
+ });
+
+ it('should allow undefined nonce in CaptchaOptions', () => {
+ const validOptionsWithoutNonce: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ invisibleSiteKey: 'test-invisible-key',
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ // nonce is optional
+ };
+
+ expect(validOptionsWithoutNonce.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaChallenge nonce integration', () => {
+ let mockClerk: any;
+
+ beforeEach(async () => {
+ // Mock clerk instance
+ mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('clerk-nonce-789'),
+ };
+
+ // Mock getCaptchaToken
+ vi.doMock('../captcha/getCaptchaToken', () => ({
+ getCaptchaToken: vi.fn().mockResolvedValue({
+ captchaToken: 'mock-token',
+ captchaWidgetType: 'invisible',
+ }),
+ }));
+ });
+
+ it('should use nonce from clerk options in invisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-invisible-key',
+ widgetType: 'invisible',
+ }),
+ );
+ });
+
+ it('should use nonce from clerk options in managedOrInvisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.managedOrInvisible({ action: 'verify' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-site-key',
+ widgetType: 'managed',
+ }),
+ );
+ });
+
+ it('should prefer explicit nonce over clerk options nonce', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({
+ action: 'signup',
+ nonce: 'explicit-nonce-override',
+ });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'explicit-nonce-override',
+ }),
+ );
+ });
+
+ it('should handle missing nonce gracefully', async () => {
+ // Mock clerk without nonce
+ const clerkWithoutNonce = {
+ ...mockClerk,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(clerkWithoutNonce);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: undefined,
+ }),
+ );
+ });
+ });
+});

packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts

@@ -12,15 +12,16 @@ export class CaptchaChallenge {
  * always use the fallback key.
  */
  public async invisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible } = retrieveCaptchaInfo(this.clerk);
+ const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible, nonce } = retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
- siteKey: captchaPublicKeyInvisible,
+ action: opts?.action,
+ captchaProvider: 'turnstile',
  invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: opts?.nonce || nonce || undefined,
+ siteKey: captchaPublicKeyInvisible,
  widgetType: 'invisible',
- captchaProvider: 'turnstile',
- action: opts?.action,
  }).catch(e => {
  if (e.captchaError) {
  return { captchaError: e.captchaError };
@@ -42,15 +43,16 @@ export class CaptchaChallenge {
  * Managed challenged start as non-interactive and escalate to interactive if necessary.
  */
  public async managedOrInvisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible } =
+ const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible, nonce } =
  retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
+ captchaProvider,
+ invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: nonce || undefined,
  siteKey: captchaSiteKey,
  widgetType: captchaWidgetType,
- invisibleSiteKey: captchaPublicKeyInvisible,
- captchaProvider,
  ...opts,
  }).catch(e => {
  if (e.captchaError) {

packages/clerk-js/src/utils/captcha/retrieveCaptchaInfo.ts

@@ -4,11 +4,15 @@ export const retrieveCaptchaInfo = (clerk: Clerk) => {
  const _environment = clerk.__unstable__environment;
  const captchaProvider = _environment ? _environment.displayConfig.captchaProvider : 'turnstile';
 
+ // Access nonce via internal options - casting to any since nonce is in IsomorphicClerkOptions but not ClerkOptions
+ const nonce = (clerk as any).__internal_getOption?.('nonce') as string | undefined;
+
  return {
  captchaSiteKey: _environment ? _environment.displayConfig.captchaPublicKey : null,
  captchaWidgetType: _environment ? _environment.displayConfig.captchaWidgetType : null,
  captchaProvider,
  captchaPublicKeyInvisible: _environment ? _environment.displayConfig.captchaPublicKeyInvisible : null,
  canUseCaptcha: _environment ? _environment.userSettings.signUp.captcha_enabled && clerk.isStandardBrowser : null,
+ nonce: nonce || undefined,
  };
 };

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -26,23 +26,23 @@ export const shouldRetryTurnstileErrorCode = (errorCode: string) => {
  return !!codesWithRetries.find(w => errorCode.startsWith(w));
 };
 
-async function loadCaptcha() {
+async function loadCaptcha(nonce?: string) {
  if (!window.turnstile) {
- await loadCaptchaFromCloudflareURL().catch(() => {
+ await loadCaptchaFromCloudflareURL(nonce).catch(() => {
  // eslint-disable-next-line @typescript-eslint/only-throw-error
  throw { captchaError: 'captcha_script_failed_to_load' };
  });
  }
  return window.turnstile;
 }
 
-async function loadCaptchaFromCloudflareURL() {
+async function loadCaptchaFromCloudflareURL(nonce?: string) {
  try {
  if (__BUILD_DISABLE_RHC__) {
  return Promise.reject(new Error('Captcha not supported in this environment'));
  }
 
- return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true });
+ return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true, nonce });
  } catch (err) {
  console.warn(
  'Clerk: Failed to load the CAPTCHA script from Cloudflare. If you see a CSP error in your browser, please add the necessary CSP rules to your app. Visit https://clerk.com/docs/security/clerk-csp for more information.',
@@ -71,9 +71,9 @@ function getCaptchaAttibutesFromElemenet(element: HTMLElement): CaptchaAttribute
  * not exist, the invisibleSiteKey is used as a fallback and the widget is rendered in a hidden div at the bottom of the body.
  */
 export const getTurnstileToken = async (opts: CaptchaOptions) => {
- const { siteKey, widgetType, invisibleSiteKey } = opts;
+ const { siteKey, widgetType, invisibleSiteKey, nonce } = opts;
  const { modalContainerQuerySelector, modalWrapperQuerySelector, closeModal, openModal } = opts;
- const captcha: Turnstile.Turnstile = await loadCaptcha();
+ const captcha: Turnstile.Turnstile = await loadCaptcha(nonce);
  const errorCodes: (string | number)[] = [];
 
  let captchaToken = '';

packages/clerk-js/src/utils/captcha/types.ts

@@ -1,15 +1,16 @@
 import type { CaptchaProvider, CaptchaWidgetType } from '@clerk/types';
 
 export type CaptchaOptions = {
- siteKey: string;
- widgetType: CaptchaWidgetType;
- invisibleSiteKey: string;
+ action?: 'verify' | 'signup' | 'heartbeat';
  captchaProvider: CaptchaProvider;
+ closeModal?: () => Promise<unknown>;
+ invisibleSiteKey: string;
  modalContainerQuerySelector?: string;
  modalWrapperQuerySelector?: string;
+ nonce?: string;
  openModal?: () => Promise<unknown>;
-closeModal?: () => Promise<unknown>;
-action?: 'verify' | 'signup' | 'heartbeat';
+siteKey: string;
+widgetType: CaptchaWidgetType;
 };
 
 export type GetCaptchaTokenReturn = {

.changeset/witty-parks-attack.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Adds Content Security Policy (CSP) nonce support to the Cloudflare Turnstile

packages/clerk-js/src/utils/__tests__/captcha.spec.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { shouldRetryTurnstileErrorCode } from '../captcha/turnstile';
+import type { CaptchaOptions } from '../captcha/types';
 
 describe('shouldRetryTurnstileErrorCode', () => {
  it.each([
@@ -23,3 +24,229 @@ describe('shouldRetryTurnstileErrorCode', () => {
  expect(shouldRetryTurnstileErrorCode(str)).toBe(expected);
  });
 });
+
+describe('Nonce support', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.resetModules();
+ });
+
+ describe('retrieveCaptchaInfo', () => {
+ it('should extract nonce from clerk options when available', async () => {
+ // Mock clerk instance with internal options
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('test-nonce-123'),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(mockClerk.__internal_getOption).toHaveBeenCalledWith('nonce');
+ expect(result.nonce).toBe('test-nonce-123');
+ expect(result.captchaSiteKey).toBe('test-site-key');
+ expect(result.captchaProvider).toBe('turnstile');
+ });
+
+ it('should return undefined nonce when not available in clerk options', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+
+ it('should handle clerk instance without __internal_getOption method', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ // No __internal_getOption method
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaOptions type support', () => {
+ it('should accept nonce in CaptchaOptions type definition', () => {
+ // This test verifies that the CaptchaOptions type includes the nonce field
+ const validOptions: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ closeModal: async () => {},
+ invisibleSiteKey: 'test-invisible-key',
+ modalContainerQuerySelector: '.modal',
+ modalWrapperQuerySelector: '.wrapper',
+ nonce: 'test-nonce-from-csp',
+ openModal: async () => {},
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ };
+
+ // If this compiles without TypeScript errors, the test passes
+ expect(validOptions.nonce).toBe('test-nonce-from-csp');
+ });
+
+ it('should allow undefined nonce in CaptchaOptions', () => {
+ const validOptionsWithoutNonce: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ invisibleSiteKey: 'test-invisible-key',
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ // nonce is optional
+ };
+
+ expect(validOptionsWithoutNonce.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaChallenge nonce integration', () => {
+ let mockClerk: any;
+
+ beforeEach(async () => {
+ // Mock clerk instance
+ mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('clerk-nonce-789'),
+ };
+
+ // Mock getCaptchaToken
+ vi.doMock('../captcha/getCaptchaToken', () => ({
+ getCaptchaToken: vi.fn().mockResolvedValue({
+ captchaToken: 'mock-token',
+ captchaWidgetType: 'invisible',
+ }),
+ }));
+ });
+
+ it('should use nonce from clerk options in invisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-invisible-key',
+ widgetType: 'invisible',
+ }),
+ );
+ });
+
+ it('should use nonce from clerk options in managedOrInvisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.managedOrInvisible({ action: 'verify' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-site-key',
+ widgetType: 'managed',
+ }),
+ );
+ });
+
+ it('should prefer explicit nonce over clerk options nonce', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({
+ action: 'signup',
+ nonce: 'explicit-nonce-override',
+ });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'explicit-nonce-override',
+ }),
+ );
+ });
+
+ it('should handle missing nonce gracefully', async () => {
+ // Mock clerk without nonce
+ const clerkWithoutNonce = {
+ ...mockClerk,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(clerkWithoutNonce);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: undefined,
+ }),
+ );
+ });
+ });
+});

packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts

@@ -12,15 +12,16 @@ export class CaptchaChallenge {
  * always use the fallback key.
  */
  public async invisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible } = retrieveCaptchaInfo(this.clerk);
+ const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible, nonce } = retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
- siteKey: captchaPublicKeyInvisible,
+ action: opts?.action,
+ captchaProvider: 'turnstile',
  invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: opts?.nonce || nonce || undefined,
+ siteKey: captchaPublicKeyInvisible,
  widgetType: 'invisible',
- captchaProvider: 'turnstile',
- action: opts?.action,
  }).catch(e => {
  if (e.captchaError) {
  return { captchaError: e.captchaError };
@@ -42,15 +43,16 @@ export class CaptchaChallenge {
  * Managed challenged start as non-interactive and escalate to interactive if necessary.
  */
  public async managedOrInvisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible } =
+ const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible, nonce } =
  retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
+ captchaProvider,
+ invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: nonce || undefined,
  siteKey: captchaSiteKey,
  widgetType: captchaWidgetType,
- invisibleSiteKey: captchaPublicKeyInvisible,
- captchaProvider,
  ...opts,
  }).catch(e => {
  if (e.captchaError) {

packages/clerk-js/src/utils/captcha/retrieveCaptchaInfo.ts

@@ -4,11 +4,15 @@ export const retrieveCaptchaInfo = (clerk: Clerk) => {
  const _environment = clerk.__unstable__environment;
  const captchaProvider = _environment ? _environment.displayConfig.captchaProvider : 'turnstile';
 
+ // Access nonce via internal options - casting to any since nonce is in IsomorphicClerkOptions but not ClerkOptions
+ const nonce = (clerk as any).__internal_getOption?.('nonce') as string | undefined;
+
  return {
  captchaSiteKey: _environment ? _environment.displayConfig.captchaPublicKey : null,
  captchaWidgetType: _environment ? _environment.displayConfig.captchaWidgetType : null,
  captchaProvider,
  captchaPublicKeyInvisible: _environment ? _environment.displayConfig.captchaPublicKeyInvisible : null,
  canUseCaptcha: _environment ? _environment.userSettings.signUp.captcha_enabled && clerk.isStandardBrowser : null,
+ nonce: nonce || undefined,
  };
 };

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -26,23 +26,23 @@ export const shouldRetryTurnstileErrorCode = (errorCode: string) => {
  return !!codesWithRetries.find(w => errorCode.startsWith(w));
 };
 
-async function loadCaptcha() {
+async function loadCaptcha(nonce?: string) {
  if (!window.turnstile) {
- await loadCaptchaFromCloudflareURL().catch(() => {
+ await loadCaptchaFromCloudflareURL(nonce).catch(() => {
  // eslint-disable-next-line @typescript-eslint/only-throw-error
  throw { captchaError: 'captcha_script_failed_to_load' };
  });
  }
  return window.turnstile;
 }
 
-async function loadCaptchaFromCloudflareURL() {
+async function loadCaptchaFromCloudflareURL(nonce?: string) {
  try {
  if (__BUILD_DISABLE_RHC__) {
  return Promise.reject(new Error('Captcha not supported in this environment'));
  }
 
- return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true });
+ return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true, nonce });
  } catch (err) {
  console.warn(
  'Clerk: Failed to load the CAPTCHA script from Cloudflare. If you see a CSP error in your browser, please add the necessary CSP rules to your app. Visit https://clerk.com/docs/security/clerk-csp for more information.',
@@ -71,9 +71,9 @@ function getCaptchaAttibutesFromElemenet(element: HTMLElement): CaptchaAttribute
  * not exist, the invisibleSiteKey is used as a fallback and the widget is rendered in a hidden div at the bottom of the body.
  */
 export const getTurnstileToken = async (opts: CaptchaOptions) => {
- const { siteKey, widgetType, invisibleSiteKey } = opts;
+ const { siteKey, widgetType, invisibleSiteKey, nonce } = opts;
  const { modalContainerQuerySelector, modalWrapperQuerySelector, closeModal, openModal } = opts;
- const captcha: Turnstile.Turnstile = await loadCaptcha();
+ const captcha: Turnstile.Turnstile = await loadCaptcha(nonce);
  const errorCodes: (string | number)[] = [];
 
  let captchaToken = '';

packages/clerk-js/src/utils/captcha/types.ts

@@ -1,15 +1,16 @@
 import type { CaptchaProvider, CaptchaWidgetType } from '@clerk/types';
 
 export type CaptchaOptions = {
- siteKey: string;
- widgetType: CaptchaWidgetType;
- invisibleSiteKey: string;
+ action?: 'verify' | 'signup' | 'heartbeat';
  captchaProvider: CaptchaProvider;
+ closeModal?: () => Promise<unknown>;
+ invisibleSiteKey: string;
  modalContainerQuerySelector?: string;
  modalWrapperQuerySelector?: string;
+ nonce?: string;
  openModal?: () => Promise<unknown>;
-closeModal?: () => Promise<unknown>;
-action?: 'verify' | 'signup' | 'heartbeat';
+siteKey: string;
+widgetType: CaptchaWidgetType;
 };
 
 export type GetCaptchaTokenReturn = {

.changeset/witty-parks-attack.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Adds Content Security Policy (CSP) nonce support to the Cloudflare Turnstile

packages/clerk-js/src/utils/__tests__/captcha.spec.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { shouldRetryTurnstileErrorCode } from '../captcha/turnstile';
+import type { CaptchaOptions } from '../captcha/types';
 
 describe('shouldRetryTurnstileErrorCode', () => {
  it.each([
@@ -23,3 +24,229 @@ describe('shouldRetryTurnstileErrorCode', () => {
  expect(shouldRetryTurnstileErrorCode(str)).toBe(expected);
  });
 });
+
+describe('Nonce support', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.resetModules();
+ });
+
+ describe('retrieveCaptchaInfo', () => {
+ it('should extract nonce from clerk options when available', async () => {
+ // Mock clerk instance with internal options
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('test-nonce-123'),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(mockClerk.__internal_getOption).toHaveBeenCalledWith('nonce');
+ expect(result.nonce).toBe('test-nonce-123');
+ expect(result.captchaSiteKey).toBe('test-site-key');
+ expect(result.captchaProvider).toBe('turnstile');
+ });
+
+ it('should return undefined nonce when not available in clerk options', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+
+ it('should handle clerk instance without __internal_getOption method', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ // No __internal_getOption method
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaOptions type support', () => {
+ it('should accept nonce in CaptchaOptions type definition', () => {
+ // This test verifies that the CaptchaOptions type includes the nonce field
+ const validOptions: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ closeModal: async () => {},
+ invisibleSiteKey: 'test-invisible-key',
+ modalContainerQuerySelector: '.modal',
+ modalWrapperQuerySelector: '.wrapper',
+ nonce: 'test-nonce-from-csp',
+ openModal: async () => {},
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ };
+
+ // If this compiles without TypeScript errors, the test passes
+ expect(validOptions.nonce).toBe('test-nonce-from-csp');
+ });
+
+ it('should allow undefined nonce in CaptchaOptions', () => {
+ const validOptionsWithoutNonce: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ invisibleSiteKey: 'test-invisible-key',
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ // nonce is optional
+ };
+
+ expect(validOptionsWithoutNonce.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaChallenge nonce integration', () => {
+ let mockClerk: any;
+
+ beforeEach(async () => {
+ // Mock clerk instance
+ mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('clerk-nonce-789'),
+ };
+
+ // Mock getCaptchaToken
+ vi.doMock('../captcha/getCaptchaToken', () => ({
+ getCaptchaToken: vi.fn().mockResolvedValue({
+ captchaToken: 'mock-token',
+ captchaWidgetType: 'invisible',
+ }),
+ }));
+ });
+
+ it('should use nonce from clerk options in invisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-invisible-key',
+ widgetType: 'invisible',
+ }),
+ );
+ });
+
+ it('should use nonce from clerk options in managedOrInvisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.managedOrInvisible({ action: 'verify' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-site-key',
+ widgetType: 'managed',
+ }),
+ );
+ });
+
+ it('should prefer explicit nonce over clerk options nonce', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({
+ action: 'signup',
+ nonce: 'explicit-nonce-override',
+ });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'explicit-nonce-override',
+ }),
+ );
+ });
+
+ it('should handle missing nonce gracefully', async () => {
+ // Mock clerk without nonce
+ const clerkWithoutNonce = {
+ ...mockClerk,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(clerkWithoutNonce);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: undefined,
+ }),
+ );
+ });
+ });
+});

packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts

@@ -12,15 +12,16 @@ export class CaptchaChallenge {
  * always use the fallback key.
  */
  public async invisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible } = retrieveCaptchaInfo(this.clerk);
+ const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible, nonce } = retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
- siteKey: captchaPublicKeyInvisible,
+ action: opts?.action,
+ captchaProvider: 'turnstile',
  invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: opts?.nonce || nonce || undefined,
+ siteKey: captchaPublicKeyInvisible,
  widgetType: 'invisible',
- captchaProvider: 'turnstile',
- action: opts?.action,
  }).catch(e => {
  if (e.captchaError) {
  return { captchaError: e.captchaError };
@@ -42,15 +43,16 @@ export class CaptchaChallenge {
  * Managed challenged start as non-interactive and escalate to interactive if necessary.
  */
  public async managedOrInvisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible } =
+ const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible, nonce } =
  retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
+ captchaProvider,
+ invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: nonce || undefined,
  siteKey: captchaSiteKey,
  widgetType: captchaWidgetType,
- invisibleSiteKey: captchaPublicKeyInvisible,
- captchaProvider,
  ...opts,
  }).catch(e => {
  if (e.captchaError) {

packages/clerk-js/src/utils/captcha/retrieveCaptchaInfo.ts

@@ -4,11 +4,15 @@ export const retrieveCaptchaInfo = (clerk: Clerk) => {
  const _environment = clerk.__unstable__environment;
  const captchaProvider = _environment ? _environment.displayConfig.captchaProvider : 'turnstile';
 
+ // Access nonce via internal options - casting to any since nonce is in IsomorphicClerkOptions but not ClerkOptions
+ const nonce = (clerk as any).__internal_getOption?.('nonce') as string | undefined;
+
  return {
  captchaSiteKey: _environment ? _environment.displayConfig.captchaPublicKey : null,
  captchaWidgetType: _environment ? _environment.displayConfig.captchaWidgetType : null,
  captchaProvider,
  captchaPublicKeyInvisible: _environment ? _environment.displayConfig.captchaPublicKeyInvisible : null,
  canUseCaptcha: _environment ? _environment.userSettings.signUp.captcha_enabled && clerk.isStandardBrowser : null,
+ nonce: nonce || undefined,
  };
 };

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -26,23 +26,23 @@ export const shouldRetryTurnstileErrorCode = (errorCode: string) => {
  return !!codesWithRetries.find(w => errorCode.startsWith(w));
 };
 
-async function loadCaptcha() {
+async function loadCaptcha(nonce?: string) {
  if (!window.turnstile) {
- await loadCaptchaFromCloudflareURL().catch(() => {
+ await loadCaptchaFromCloudflareURL(nonce).catch(() => {
  // eslint-disable-next-line @typescript-eslint/only-throw-error
  throw { captchaError: 'captcha_script_failed_to_load' };
  });
  }
  return window.turnstile;
 }
 
-async function loadCaptchaFromCloudflareURL() {
+async function loadCaptchaFromCloudflareURL(nonce?: string) {
  try {
  if (__BUILD_DISABLE_RHC__) {
  return Promise.reject(new Error('Captcha not supported in this environment'));
  }
 
- return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true });
+ return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true, nonce });
  } catch (err) {
  console.warn(
  'Clerk: Failed to load the CAPTCHA script from Cloudflare. If you see a CSP error in your browser, please add the necessary CSP rules to your app. Visit https://clerk.com/docs/security/clerk-csp for more information.',
@@ -71,9 +71,9 @@ function getCaptchaAttibutesFromElemenet(element: HTMLElement): CaptchaAttribute
  * not exist, the invisibleSiteKey is used as a fallback and the widget is rendered in a hidden div at the bottom of the body.
  */
 export const getTurnstileToken = async (opts: CaptchaOptions) => {
- const { siteKey, widgetType, invisibleSiteKey } = opts;
+ const { siteKey, widgetType, invisibleSiteKey, nonce } = opts;
  const { modalContainerQuerySelector, modalWrapperQuerySelector, closeModal, openModal } = opts;
- const captcha: Turnstile.Turnstile = await loadCaptcha();
+ const captcha: Turnstile.Turnstile = await loadCaptcha(nonce);
  const errorCodes: (string | number)[] = [];
 
  let captchaToken = '';

packages/clerk-js/src/utils/captcha/types.ts

@@ -1,15 +1,16 @@
 import type { CaptchaProvider, CaptchaWidgetType } from '@clerk/types';
 
 export type CaptchaOptions = {
- siteKey: string;
- widgetType: CaptchaWidgetType;
- invisibleSiteKey: string;
+ action?: 'verify' | 'signup' | 'heartbeat';
  captchaProvider: CaptchaProvider;
+ closeModal?: () => Promise<unknown>;
+ invisibleSiteKey: string;
  modalContainerQuerySelector?: string;
  modalWrapperQuerySelector?: string;
+ nonce?: string;
  openModal?: () => Promise<unknown>;
-closeModal?: () => Promise<unknown>;
-action?: 'verify' | 'signup' | 'heartbeat';
+siteKey: string;
+widgetType: CaptchaWidgetType;
 };
 
 export type GetCaptchaTokenReturn = {

.changeset/witty-parks-attack.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Adds Content Security Policy (CSP) nonce support to the Cloudflare Turnstile

packages/clerk-js/src/utils/__tests__/captcha.spec.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { shouldRetryTurnstileErrorCode } from '../captcha/turnstile';
+import type { CaptchaOptions } from '../captcha/types';
 
 describe('shouldRetryTurnstileErrorCode', () => {
  it.each([
@@ -23,3 +24,229 @@ describe('shouldRetryTurnstileErrorCode', () => {
  expect(shouldRetryTurnstileErrorCode(str)).toBe(expected);
  });
 });
+
+describe('Nonce support', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.resetModules();
+ });
+
+ describe('retrieveCaptchaInfo', () => {
+ it('should extract nonce from clerk options when available', async () => {
+ // Mock clerk instance with internal options
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('test-nonce-123'),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(mockClerk.__internal_getOption).toHaveBeenCalledWith('nonce');
+ expect(result.nonce).toBe('test-nonce-123');
+ expect(result.captchaSiteKey).toBe('test-site-key');
+ expect(result.captchaProvider).toBe('turnstile');
+ });
+
+ it('should return undefined nonce when not available in clerk options', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+
+ it('should handle clerk instance without __internal_getOption method', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ // No __internal_getOption method
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaOptions type support', () => {
+ it('should accept nonce in CaptchaOptions type definition', () => {
+ // This test verifies that the CaptchaOptions type includes the nonce field
+ const validOptions: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ closeModal: async () => {},
+ invisibleSiteKey: 'test-invisible-key',
+ modalContainerQuerySelector: '.modal',
+ modalWrapperQuerySelector: '.wrapper',
+ nonce: 'test-nonce-from-csp',
+ openModal: async () => {},
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ };
+
+ // If this compiles without TypeScript errors, the test passes
+ expect(validOptions.nonce).toBe('test-nonce-from-csp');
+ });
+
+ it('should allow undefined nonce in CaptchaOptions', () => {
+ const validOptionsWithoutNonce: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ invisibleSiteKey: 'test-invisible-key',
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ // nonce is optional
+ };
+
+ expect(validOptionsWithoutNonce.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaChallenge nonce integration', () => {
+ let mockClerk: any;
+
+ beforeEach(async () => {
+ // Mock clerk instance
+ mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('clerk-nonce-789'),
+ };
+
+ // Mock getCaptchaToken
+ vi.doMock('../captcha/getCaptchaToken', () => ({
+ getCaptchaToken: vi.fn().mockResolvedValue({
+ captchaToken: 'mock-token',
+ captchaWidgetType: 'invisible',
+ }),
+ }));
+ });
+
+ it('should use nonce from clerk options in invisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-invisible-key',
+ widgetType: 'invisible',
+ }),
+ );
+ });
+
+ it('should use nonce from clerk options in managedOrInvisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.managedOrInvisible({ action: 'verify' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-site-key',
+ widgetType: 'managed',
+ }),
+ );
+ });
+
+ it('should prefer explicit nonce over clerk options nonce', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({
+ action: 'signup',
+ nonce: 'explicit-nonce-override',
+ });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'explicit-nonce-override',
+ }),
+ );
+ });
+
+ it('should handle missing nonce gracefully', async () => {
+ // Mock clerk without nonce
+ const clerkWithoutNonce = {
+ ...mockClerk,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(clerkWithoutNonce);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: undefined,
+ }),
+ );
+ });
+ });
+});

packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts

@@ -12,15 +12,16 @@ export class CaptchaChallenge {
  * always use the fallback key.
  */
  public async invisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible } = retrieveCaptchaInfo(this.clerk);
+ const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible, nonce } = retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
- siteKey: captchaPublicKeyInvisible,
+ action: opts?.action,
+ captchaProvider: 'turnstile',
  invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: opts?.nonce || nonce || undefined,
+ siteKey: captchaPublicKeyInvisible,
  widgetType: 'invisible',
- captchaProvider: 'turnstile',
- action: opts?.action,
  }).catch(e => {
  if (e.captchaError) {
  return { captchaError: e.captchaError };
@@ -42,15 +43,16 @@ export class CaptchaChallenge {
  * Managed challenged start as non-interactive and escalate to interactive if necessary.
  */
  public async managedOrInvisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible } =
+ const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible, nonce } =
  retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
+ captchaProvider,
+ invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: nonce || undefined,
  siteKey: captchaSiteKey,
  widgetType: captchaWidgetType,
- invisibleSiteKey: captchaPublicKeyInvisible,
- captchaProvider,
  ...opts,
  }).catch(e => {
  if (e.captchaError) {

packages/clerk-js/src/utils/captcha/retrieveCaptchaInfo.ts

@@ -4,11 +4,15 @@ export const retrieveCaptchaInfo = (clerk: Clerk) => {
  const _environment = clerk.__unstable__environment;
  const captchaProvider = _environment ? _environment.displayConfig.captchaProvider : 'turnstile';
 
+ // Access nonce via internal options - casting to any since nonce is in IsomorphicClerkOptions but not ClerkOptions
+ const nonce = (clerk as any).__internal_getOption?.('nonce') as string | undefined;
+
  return {
  captchaSiteKey: _environment ? _environment.displayConfig.captchaPublicKey : null,
  captchaWidgetType: _environment ? _environment.displayConfig.captchaWidgetType : null,
  captchaProvider,
  captchaPublicKeyInvisible: _environment ? _environment.displayConfig.captchaPublicKeyInvisible : null,
  canUseCaptcha: _environment ? _environment.userSettings.signUp.captcha_enabled && clerk.isStandardBrowser : null,
+ nonce: nonce || undefined,
  };
 };

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -26,23 +26,23 @@ export const shouldRetryTurnstileErrorCode = (errorCode: string) => {
  return !!codesWithRetries.find(w => errorCode.startsWith(w));
 };
 
-async function loadCaptcha() {
+async function loadCaptcha(nonce?: string) {
  if (!window.turnstile) {
- await loadCaptchaFromCloudflareURL().catch(() => {
+ await loadCaptchaFromCloudflareURL(nonce).catch(() => {
  // eslint-disable-next-line @typescript-eslint/only-throw-error
  throw { captchaError: 'captcha_script_failed_to_load' };
  });
  }
  return window.turnstile;
 }
 
-async function loadCaptchaFromCloudflareURL() {
+async function loadCaptchaFromCloudflareURL(nonce?: string) {
  try {
  if (__BUILD_DISABLE_RHC__) {
  return Promise.reject(new Error('Captcha not supported in this environment'));
  }
 
- return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true });
+ return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true, nonce });
  } catch (err) {
  console.warn(
  'Clerk: Failed to load the CAPTCHA script from Cloudflare. If you see a CSP error in your browser, please add the necessary CSP rules to your app. Visit https://clerk.com/docs/security/clerk-csp for more information.',
@@ -71,9 +71,9 @@ function getCaptchaAttibutesFromElemenet(element: HTMLElement): CaptchaAttribute
  * not exist, the invisibleSiteKey is used as a fallback and the widget is rendered in a hidden div at the bottom of the body.
  */
 export const getTurnstileToken = async (opts: CaptchaOptions) => {
- const { siteKey, widgetType, invisibleSiteKey } = opts;
+ const { siteKey, widgetType, invisibleSiteKey, nonce } = opts;
  const { modalContainerQuerySelector, modalWrapperQuerySelector, closeModal, openModal } = opts;
- const captcha: Turnstile.Turnstile = await loadCaptcha();
+ const captcha: Turnstile.Turnstile = await loadCaptcha(nonce);
  const errorCodes: (string | number)[] = [];
 
  let captchaToken = '';

packages/clerk-js/src/utils/captcha/types.ts

@@ -1,15 +1,16 @@
 import type { CaptchaProvider, CaptchaWidgetType } from '@clerk/types';
 
 export type CaptchaOptions = {
- siteKey: string;
- widgetType: CaptchaWidgetType;
- invisibleSiteKey: string;
+ action?: 'verify' | 'signup' | 'heartbeat';
  captchaProvider: CaptchaProvider;
+ closeModal?: () => Promise<unknown>;
+ invisibleSiteKey: string;
  modalContainerQuerySelector?: string;
  modalWrapperQuerySelector?: string;
+ nonce?: string;
  openModal?: () => Promise<unknown>;
-closeModal?: () => Promise<unknown>;
-action?: 'verify' | 'signup' | 'heartbeat';
+siteKey: string;
+widgetType: CaptchaWidgetType;
 };
 
 export type GetCaptchaTokenReturn = {

.changeset/witty-parks-attack.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Adds Content Security Policy (CSP) nonce support to the Cloudflare Turnstile

packages/clerk-js/src/utils/__tests__/captcha.spec.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { shouldRetryTurnstileErrorCode } from '../captcha/turnstile';
+import type { CaptchaOptions } from '../captcha/types';
 
 describe('shouldRetryTurnstileErrorCode', () => {
  it.each([
@@ -23,3 +24,229 @@ describe('shouldRetryTurnstileErrorCode', () => {
  expect(shouldRetryTurnstileErrorCode(str)).toBe(expected);
  });
 });
+
+describe('Nonce support', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ vi.resetModules();
+ });
+
+ describe('retrieveCaptchaInfo', () => {
+ it('should extract nonce from clerk options when available', async () => {
+ // Mock clerk instance with internal options
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('test-nonce-123'),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(mockClerk.__internal_getOption).toHaveBeenCalledWith('nonce');
+ expect(result.nonce).toBe('test-nonce-123');
+ expect(result.captchaSiteKey).toBe('test-site-key');
+ expect(result.captchaProvider).toBe('turnstile');
+ });
+
+ it('should return undefined nonce when not available in clerk options', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+
+ it('should handle clerk instance without __internal_getOption method', async () => {
+ const mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ // No __internal_getOption method
+ };
+
+ const { retrieveCaptchaInfo } = await import('../captcha/retrieveCaptchaInfo');
+ const result = retrieveCaptchaInfo(mockClerk as any);
+
+ expect(result.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaOptions type support', () => {
+ it('should accept nonce in CaptchaOptions type definition', () => {
+ // This test verifies that the CaptchaOptions type includes the nonce field
+ const validOptions: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ closeModal: async () => {},
+ invisibleSiteKey: 'test-invisible-key',
+ modalContainerQuerySelector: '.modal',
+ modalWrapperQuerySelector: '.wrapper',
+ nonce: 'test-nonce-from-csp',
+ openModal: async () => {},
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ };
+
+ // If this compiles without TypeScript errors, the test passes
+ expect(validOptions.nonce).toBe('test-nonce-from-csp');
+ });
+
+ it('should allow undefined nonce in CaptchaOptions', () => {
+ const validOptionsWithoutNonce: CaptchaOptions = {
+ action: 'signup',
+ captchaProvider: 'turnstile',
+ invisibleSiteKey: 'test-invisible-key',
+ siteKey: 'test-site-key',
+ widgetType: 'invisible',
+ // nonce is optional
+ };
+
+ expect(validOptionsWithoutNonce.nonce).toBeUndefined();
+ });
+ });
+
+ describe('CaptchaChallenge nonce integration', () => {
+ let mockClerk: any;
+
+ beforeEach(async () => {
+ // Mock clerk instance
+ mockClerk = {
+ __unstable__environment: {
+ displayConfig: {
+ captchaProvider: 'turnstile',
+ captchaPublicKey: 'test-site-key',
+ captchaWidgetType: 'managed',
+ captchaPublicKeyInvisible: 'test-invisible-key',
+ },
+ userSettings: {
+ signUp: {
+ captcha_enabled: true,
+ },
+ },
+ },
+ isStandardBrowser: true,
+ __internal_getOption: vi.fn().mockReturnValue('clerk-nonce-789'),
+ };
+
+ // Mock getCaptchaToken
+ vi.doMock('../captcha/getCaptchaToken', () => ({
+ getCaptchaToken: vi.fn().mockResolvedValue({
+ captchaToken: 'mock-token',
+ captchaWidgetType: 'invisible',
+ }),
+ }));
+ });
+
+ it('should use nonce from clerk options in invisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-invisible-key',
+ widgetType: 'invisible',
+ }),
+ );
+ });
+
+ it('should use nonce from clerk options in managedOrInvisible challenge', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.managedOrInvisible({ action: 'verify' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'clerk-nonce-789',
+ captchaProvider: 'turnstile',
+ siteKey: 'test-site-key',
+ widgetType: 'managed',
+ }),
+ );
+ });
+
+ it('should prefer explicit nonce over clerk options nonce', async () => {
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(mockClerk);
+ await challenge.invisible({
+ action: 'signup',
+ nonce: 'explicit-nonce-override',
+ });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: 'explicit-nonce-override',
+ }),
+ );
+ });
+
+ it('should handle missing nonce gracefully', async () => {
+ // Mock clerk without nonce
+ const clerkWithoutNonce = {
+ ...mockClerk,
+ __internal_getOption: vi.fn().mockReturnValue(undefined),
+ };
+
+ const { getCaptchaToken } = await import('../captcha/getCaptchaToken');
+ const { CaptchaChallenge } = await import('../captcha/CaptchaChallenge');
+
+ const challenge = new CaptchaChallenge(clerkWithoutNonce);
+ await challenge.invisible({ action: 'signup' });
+
+ expect(getCaptchaToken).toHaveBeenCalledWith(
+ expect.objectContaining({
+ nonce: undefined,
+ }),
+ );
+ });
+ });
+});

packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts

@@ -12,15 +12,16 @@ export class CaptchaChallenge {
  * always use the fallback key.
  */
  public async invisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible } = retrieveCaptchaInfo(this.clerk);
+ const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible, nonce } = retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
- siteKey: captchaPublicKeyInvisible,
+ action: opts?.action,
+ captchaProvider: 'turnstile',
  invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: opts?.nonce || nonce || undefined,
+ siteKey: captchaPublicKeyInvisible,
  widgetType: 'invisible',
- captchaProvider: 'turnstile',
- action: opts?.action,
  }).catch(e => {
  if (e.captchaError) {
  return { captchaError: e.captchaError };
@@ -42,15 +43,16 @@ export class CaptchaChallenge {
  * Managed challenged start as non-interactive and escalate to interactive if necessary.
  */
  public async managedOrInvisible(opts?: Partial<CaptchaOptions>) {
- const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible } =
+ const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible, nonce } =
  retrieveCaptchaInfo(this.clerk);
 
  if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
  const captchaResult = await getCaptchaToken({
+ captchaProvider,
+ invisibleSiteKey: captchaPublicKeyInvisible,
+ nonce: nonce || undefined,
  siteKey: captchaSiteKey,
  widgetType: captchaWidgetType,
- invisibleSiteKey: captchaPublicKeyInvisible,
- captchaProvider,
  ...opts,
  }).catch(e => {
  if (e.captchaError) {

packages/clerk-js/src/utils/captcha/retrieveCaptchaInfo.ts

@@ -4,11 +4,15 @@ export const retrieveCaptchaInfo = (clerk: Clerk) => {
  const _environment = clerk.__unstable__environment;
  const captchaProvider = _environment ? _environment.displayConfig.captchaProvider : 'turnstile';
 
+ // Access nonce via internal options - casting to any since nonce is in IsomorphicClerkOptions but not ClerkOptions
+ const nonce = (clerk as any).__internal_getOption?.('nonce') as string | undefined;
+
  return {
  captchaSiteKey: _environment ? _environment.displayConfig.captchaPublicKey : null,
  captchaWidgetType: _environment ? _environment.displayConfig.captchaWidgetType : null,
  captchaProvider,
  captchaPublicKeyInvisible: _environment ? _environment.displayConfig.captchaPublicKeyInvisible : null,
  canUseCaptcha: _environment ? _environment.userSettings.signUp.captcha_enabled && clerk.isStandardBrowser : null,
+ nonce: nonce || undefined,
  };
 };

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -26,23 +26,23 @@ export const shouldRetryTurnstileErrorCode = (errorCode: string) => {
  return !!codesWithRetries.find(w => errorCode.startsWith(w));
 };
 
-async function loadCaptcha() {
+async function loadCaptcha(nonce?: string) {
  if (!window.turnstile) {
- await loadCaptchaFromCloudflareURL().catch(() => {
+ await loadCaptchaFromCloudflareURL(nonce).catch(() => {
  // eslint-disable-next-line @typescript-eslint/only-throw-error
  throw { captchaError: 'captcha_script_failed_to_load' };
  });
  }
  return window.turnstile;
 }
 
-async function loadCaptchaFromCloudflareURL() {
+async function loadCaptchaFromCloudflareURL(nonce?: string) {
  try {
  if (__BUILD_DISABLE_RHC__) {
  return Promise.reject(new Error('Captcha not supported in this environment'));
  }
 
- return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true });
+ return await loadScript(CLOUDFLARE_TURNSTILE_ORIGINAL_URL, { defer: true, nonce });
  } catch (err) {
  console.warn(
  'Clerk: Failed to load the CAPTCHA script from Cloudflare. If you see a CSP error in your browser, please add the necessary CSP rules to your app. Visit https://clerk.com/docs/security/clerk-csp for more information.',
@@ -71,9 +71,9 @@ function getCaptchaAttibutesFromElemenet(element: HTMLElement): CaptchaAttribute
  * not exist, the invisibleSiteKey is used as a fallback and the widget is rendered in a hidden div at the bottom of the body.
  */
 export const getTurnstileToken = async (opts: CaptchaOptions) => {
- const { siteKey, widgetType, invisibleSiteKey } = opts;
+ const { siteKey, widgetType, invisibleSiteKey, nonce } = opts;
  const { modalContainerQuerySelector, modalWrapperQuerySelector, closeModal, openModal } = opts;
- const captcha: Turnstile.Turnstile = await loadCaptcha();
+ const captcha: Turnstile.Turnstile = await loadCaptcha(nonce);
  const errorCodes: (string | number)[] = [];
 
  let captchaToken = '';

packages/clerk-js/src/utils/captcha/types.ts

@@ -1,15 +1,16 @@
 import type { CaptchaProvider, CaptchaWidgetType } from '@clerk/types';
 
 export type CaptchaOptions = {
- siteKey: string;
- widgetType: CaptchaWidgetType;
- invisibleSiteKey: string;
+ action?: 'verify' | 'signup' | 'heartbeat';
  captchaProvider: CaptchaProvider;
+ closeModal?: () => Promise<unknown>;
+ invisibleSiteKey: string;
  modalContainerQuerySelector?: string;
  modalWrapperQuerySelector?: string;
+ nonce?: string;
  openModal?: () => Promise<unknown>;
-closeModal?: () => Promise<unknown>;
-action?: 'verify' | 'signup' | 'heartbeat';
+siteKey: string;
+widgetType: CaptchaWidgetType;
 };
 
 export type GetCaptchaTokenReturn = {