feat(clerk-js): Add initial protect integration

.changeset/beige-sloths-provide.md

@@ -0,0 +1,6 @@
+---
+"@clerk/clerk-js": minor
+"@clerk/shared": minor
+---
+
+Introduce ProtectConfig resource and Protect loader integration.

integration/tests/protect-service.test.ts

@@ -0,0 +1,76 @@
+import type { ProtectConfigJSON } from '@clerk/shared/types';
+import type { Page } from '@playwright/test';
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../presets';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+const mockProtectSettings = async (page: Page, config?: ProtectConfigJSON) => {
+ await page.route('*/**/v1/environment*', async route => {
+ const response = await route.fetch();
+ const json = await response.json();
+ const newJson = {
+ ...json,
+ ...(config ? { protect_config: config } : {}),
+ };
+ await route.fulfill({ response, json: newJson });
+ });
+};
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('Clerk Protect checks @generic', ({ app }) => {
+ test.describe.configure({ mode: 'parallel' });
+
+ test.afterAll(async () => {
+ await app.teardown();
+ });
+
+ test('should add loader script when protect_config.loader is set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 1.0,
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-1', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-1')).toHaveAttribute('type', 'module');
+ });
+
+ test('should not add loader script when protect_config.loader is set and rollout 0.00', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 0, // force 0% rollout, should not materialize
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-2', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-2')).toHaveCount(0);
+ });
+
+ test('should not create loader element when protect_config.loader is not set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page);
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ // Playwright locators are always objects, never undefined
+ await expect(page.locator('#test-protect-loader')).toHaveCount(0);
+ });
+});

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.channel.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "65KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },

packages/clerk-js/src/core/clerk.ts

@@ -158,6 +158,7 @@ import { createClientFromJwt } from './jwt-client';
 import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
+import { Protect } from './protect';
 import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
 import { getTaskEndpoint, navigateIfTaskExists, warnMissingPendingTaskHandlers } from './sessionTasks';
 import { State } from './state';
@@ -227,6 +228,7 @@ export class Clerk implements ClerkInterface {
  #domain: DomainOrProxyUrl['domain'];
  #proxyUrl: DomainOrProxyUrl['proxyUrl'];
  #authService?: AuthCookieService;
+ #protect?: Protect;
  #captchaHeartbeat?: CaptchaHeartbeat;
  #broadcastChannel: BroadcastChannel | null = null;
  #componentControls?: ReturnType<MountComponentRenderer> | null;
@@ -429,6 +431,7 @@ export class Clerk implements ClerkInterface {
 
  // This line is used for the piggy-backing mechanism
  BaseResource.clerk = this;
+ this.#protect = new Protect();
  }
 
  public getFapiClient = (): FapiClient => this.#fapiClient;
@@ -516,6 +519,7 @@ export class Clerk implements ClerkInterface {
  ...(telemetryEnabled && this.telemetry ? { telemetryCollector: this.telemetry } : {}),
  });
  }
+ this.#protect?.load(this.environment as Environment);
  debugLogger.info('load() complete', {}, 'clerk');
  } catch (error) {
  this.#publicEventBus.emit(clerkEvents.Status, 'error');

packages/clerk-js/src/core/protect.ts

@@ -0,0 +1,97 @@
+import { inBrowser } from '@clerk/shared/browser';
+import { logger } from '@clerk/shared/logger';
+import type { ProtectLoader } from '@clerk/shared/types';
+
+import type { Environment } from './resources';
+export class Protect {
+ #initialized: boolean = false;
+
+ load(env: Environment): void {
+ const config = env?.protectConfig;
+
+ if (!config?.loaders || !Array.isArray(config.loaders) || config.loaders.length === 0) {
+ // not enabled or no protect config available
+ return;
+ } else if (this.#initialized) {
+ // already initialized - do nothing
+ return;
+ } else if (!inBrowser()) {
+ // no document: not running browser?
+ return;
+ }
+
+ // here rather than at end to mark as initialized even if load fails.
+ this.#initialized = true;
+
+ for (const loader of config.loaders) {
+ try {
+ this.applyLoader(loader);
+ } catch (error) {
+ logger.warnOnce(`[protect] failed to apply loader: ${error}`);
+ }
+ }
+ }
+
+ // apply individual loader
+ applyLoader(loader: ProtectLoader) {
+ // we use rollout for percentage based rollouts (as the environment file is cached)
+ if (loader.rollout !== undefined) {
+ const rollout = loader.rollout;
+ if (typeof rollout !== 'number' || rollout < 0) {
+ // invalid rollout percentage - do nothing
+ logger.warnOnce(`[protect] loader rollout value is invalid: ${rollout}`);
+ return;
+ }
+ if (rollout === 0 || Math.random() > rollout) {
+ // not in rollout percentage - do nothing
+ return;
+ }
+ }
+
+ const type = loader.type || 'script';
+ const target = loader.target || 'body';
+
+ const element = document.createElement(type);
+
+ if (loader.attributes) {
+ for (const [key, value] of Object.entries(loader.attributes)) {
+ switch (typeof value) {
+ case 'string':
+ case 'number':
+ case 'boolean':
+ element.setAttribute(key, String(value));
+ break;
+ default:
+ // illegal to set.
+ logger.warnOnce(`[protect] loader attribute is invalid type: ${key}=${value}`);
+ break;
+ }
+ }
+ }
+
+ if (loader.textContent && typeof loader.textContent === 'string') {
+ element.textContent = loader.textContent;
+ }
+
+ switch (target) {
+ case 'head':
+ document.head.appendChild(element);
+ break;
+ case 'body':
+ document.body.appendChild(element);
+ break;
+ default:
+ if (target?.startsWith('#')) {
+ const targetElement = document.getElementById(target.substring(1));
+ if (!targetElement) {
+ logger.warnOnce(`[protect] loader target element not found: ${target}`);
+ return;
+ }
+ targetElement.appendChild(element);
+ return;
+ }
+ logger.warnOnce(`[protect] loader target is invalid: ${target}`);
+ break;
+ }
+ }
+}

packages/clerk-js/src/core/resources/Environment.ts

@@ -6,12 +6,13 @@ import type {
  EnvironmentJSONSnapshot,
  EnvironmentResource,
  OrganizationSettingsResource,
+ ProtectConfigResource,
  UserSettingsResource,
 } from '@clerk/shared/types';
 
 import { eventBus, events } from '../../core/events';
 import { APIKeySettings } from './APIKeySettings';
-import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, UserSettings } from './internal';
+import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, ProtectConfig, UserSettings } from './internal';
 import { OrganizationSettings } from './OrganizationSettings';
 
 export class Environment extends BaseResource implements EnvironmentResource {
@@ -26,6 +27,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  organizationSettings: OrganizationSettingsResource = new OrganizationSettings();
  commerceSettings: CommerceSettingsResource = new CommerceSettings();
  apiKeysSettings: APIKeySettings = new APIKeySettings();
+ protectConfig: ProtectConfigResource = new ProtectConfig();
 
  public static getInstance(): Environment {
  if (!Environment.instance) {
@@ -54,6 +56,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  this.userSettings = new UserSettings(data.user_settings);
  this.commerceSettings = new CommerceSettings(data.commerce_settings);
  this.apiKeysSettings = new APIKeySettings(data.api_keys_settings);
+ this.protectConfig = new ProtectConfig(data.protect_config);
 
  return this;
  }
@@ -95,6 +98,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  user_settings: this.userSettings.__internal_toSnapshot(),
  commerce_settings: this.commerceSettings.__internal_toSnapshot(),
  api_keys_settings: this.apiKeysSettings.__internal_toSnapshot(),
+ protect_config: this.protectConfig.__internal_toSnapshot(),
  };
  }
 }

packages/clerk-js/src/core/resources/ProtectConfig.ts

@@ -0,0 +1,39 @@
+import type {
+ ProtectConfigJSON,
+ ProtectConfigJSONSnapshot,
+ ProtectConfigResource,
+ ProtectLoader,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class ProtectConfig extends BaseResource implements ProtectConfigResource {
+ id: string = '';
+ loaders?: ProtectLoader[];
+ rollout?: number;
+
+ public constructor(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null = null) {
+ super();
+
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = this.withDefault(data.id, this.id);
+ this.loaders = this.withDefault(data.loaders, this.loaders);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): ProtectConfigJSONSnapshot {
+ return {
+ object: 'protect_config',
+ id: this.id,
+ loaders: this.loaders,
+ };
+ }
+}

packages/clerk-js/src/core/resources/internal.ts

@@ -29,6 +29,7 @@ export * from './OrganizationSuggestion';
 export * from './SamlAccount';
 export * from './Session';
 export * from './Passkey';
+export * from './ProtectConfig';
 export * from './PublicUserData';
 export * from './SessionWithActivities';
 export * from './SignIn';

packages/shared/src/types/environment.ts

@@ -3,6 +3,7 @@ import type { AuthConfigResource } from './authConfig';
 import type { CommerceSettingsResource } from './commerceSettings';
 import type { DisplayConfigResource } from './displayConfig';
 import type { OrganizationSettingsResource } from './organizationSettings';
+import type { ProtectConfigResource } from './protectConfig';
 import type { ClerkResource } from './resource';
 import type { EnvironmentJSONSnapshot } from './snapshots';
 import type { UserSettingsResource } from './userSettings';
@@ -14,6 +15,7 @@ export interface EnvironmentResource extends ClerkResource {
  displayConfig: DisplayConfigResource;
  commerceSettings: CommerceSettingsResource;
  apiKeysSettings: APIKeysSettingsResource;
+ protectConfig: ProtectConfigResource;
  isSingleSession: () => boolean;
  isProduction: () => boolean;
  isDevelopmentOrStaging: () => boolean;

packages/shared/src/types/index.ts

@@ -46,6 +46,7 @@ export type * from './permission';
 export type * from './phoneCodeChannel';
 export type * from './phoneNumber';
 export type * from './protect';
+export type * from './protectConfig';
 export type * from './redirects';
 export type * from './resource';
 export type * from './role';

packages/shared/src/types/json.ts

@@ -25,6 +25,7 @@ import type { OrganizationCustomRoleKey, OrganizationPermissionKey } from './org
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { OrganizationSuggestionStatus } from './organizationSuggestion';
 import type { PhoneCodeChannel } from './phoneCodeChannel';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SamlIdpSlug } from './saml';
 import type { SessionStatus, SessionTask } from './session';
 import type { SessionVerificationLevel, SessionVerificationStatus } from './sessionVerification';
@@ -90,6 +91,7 @@ export interface EnvironmentJSON extends ClerkResourceJSON {
  maintenance_mode: boolean;
  organization_settings: OrganizationSettingsJSON;
  user_settings: UserSettingsJSON;
+ protect_config: ProtectConfigJSON;
 }
 
 export type LastAuthenticationStrategy =

packages/shared/src/types/protectConfig.ts

@@ -0,0 +1,22 @@
+import type { ClerkResource } from './resource';
+import type { ProtectConfigJSONSnapshot } from './snapshots';
+
+export interface ProtectLoader {
+ rollout?: number;
+ target: 'head' | 'body' | `#${string}`;
+ type: string;
+ attributes?: Record<string, string | number | boolean>;
+ textContent?: string;
+}
+
+export interface ProtectConfigJSON {
+ object: 'protect_config';
+ id: string;
+ loaders?: ProtectLoader[];
+}
+
+export interface ProtectConfigResource extends ClerkResource {
+ id: string;
+ loaders?: ProtectLoader[];
+ __internal_toSnapshot: () => ProtectConfigJSONSnapshot;
+}

packages/shared/src/types/snapshots.ts

@@ -31,6 +31,7 @@ import type {
  Web3WalletJSON,
 } from './json';
 import type { OrganizationSettingsJSON } from './organizationSettings';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SignInJSON } from './signIn';
 import type { UserSettingsJSON } from './userSettings';
 import type { Nullable, Override } from './utils';
@@ -119,6 +120,8 @@ export type EnvironmentJSONSnapshot = EnvironmentJSON;
 
 export type DisplayConfigJSONSnapshot = DisplayConfigJSON;
 
+export type ProtectConfigJSONSnapshot = ProtectConfigJSON;
+
 export type EmailAddressJSONSnapshot = Override<
  EmailAddressJSON,
  {

.changeset/beige-sloths-provide.md

@@ -0,0 +1,6 @@
+---
+"@clerk/clerk-js": minor
+"@clerk/shared": minor
+---
+
+Introduce ProtectConfig resource and Protect loader integration.

integration/tests/protect-service.test.ts

@@ -0,0 +1,76 @@
+import type { ProtectConfigJSON } from '@clerk/shared/types';
+import type { Page } from '@playwright/test';
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../presets';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+const mockProtectSettings = async (page: Page, config?: ProtectConfigJSON) => {
+ await page.route('*/**/v1/environment*', async route => {
+ const response = await route.fetch();
+ const json = await response.json();
+ const newJson = {
+ ...json,
+ ...(config ? { protect_config: config } : {}),
+ };
+ await route.fulfill({ response, json: newJson });
+ });
+};
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('Clerk Protect checks @generic', ({ app }) => {
+ test.describe.configure({ mode: 'parallel' });
+
+ test.afterAll(async () => {
+ await app.teardown();
+ });
+
+ test('should add loader script when protect_config.loader is set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 1.0,
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-1', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-1')).toHaveAttribute('type', 'module');
+ });
+
+ test('should not add loader script when protect_config.loader is set and rollout 0.00', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 0, // force 0% rollout, should not materialize
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-2', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-2')).toHaveCount(0);
+ });
+
+ test('should not create loader element when protect_config.loader is not set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page);
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ // Playwright locators are always objects, never undefined
+ await expect(page.locator('#test-protect-loader')).toHaveCount(0);
+ });
+});

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.channel.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "65KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },

packages/clerk-js/src/core/clerk.ts

@@ -158,6 +158,7 @@ import { createClientFromJwt } from './jwt-client';
 import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
+import { Protect } from './protect';
 import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
 import { getTaskEndpoint, navigateIfTaskExists, warnMissingPendingTaskHandlers } from './sessionTasks';
 import { State } from './state';
@@ -227,6 +228,7 @@ export class Clerk implements ClerkInterface {
  #domain: DomainOrProxyUrl['domain'];
  #proxyUrl: DomainOrProxyUrl['proxyUrl'];
  #authService?: AuthCookieService;
+ #protect?: Protect;
  #captchaHeartbeat?: CaptchaHeartbeat;
  #broadcastChannel: BroadcastChannel | null = null;
  #componentControls?: ReturnType<MountComponentRenderer> | null;
@@ -429,6 +431,7 @@ export class Clerk implements ClerkInterface {
 
  // This line is used for the piggy-backing mechanism
  BaseResource.clerk = this;
+ this.#protect = new Protect();
  }
 
  public getFapiClient = (): FapiClient => this.#fapiClient;
@@ -516,6 +519,7 @@ export class Clerk implements ClerkInterface {
  ...(telemetryEnabled && this.telemetry ? { telemetryCollector: this.telemetry } : {}),
  });
  }
+ this.#protect?.load(this.environment as Environment);
  debugLogger.info('load() complete', {}, 'clerk');
  } catch (error) {
  this.#publicEventBus.emit(clerkEvents.Status, 'error');

packages/clerk-js/src/core/protect.ts

@@ -0,0 +1,97 @@
+import { inBrowser } from '@clerk/shared/browser';
+import { logger } from '@clerk/shared/logger';
+import type { ProtectLoader } from '@clerk/shared/types';
+
+import type { Environment } from './resources';
+export class Protect {
+ #initialized: boolean = false;
+
+ load(env: Environment): void {
+ const config = env?.protectConfig;
+
+ if (!config?.loaders || !Array.isArray(config.loaders) || config.loaders.length === 0) {
+ // not enabled or no protect config available
+ return;
+ } else if (this.#initialized) {
+ // already initialized - do nothing
+ return;
+ } else if (!inBrowser()) {
+ // no document: not running browser?
+ return;
+ }
+
+ // here rather than at end to mark as initialized even if load fails.
+ this.#initialized = true;
+
+ for (const loader of config.loaders) {
+ try {
+ this.applyLoader(loader);
+ } catch (error) {
+ logger.warnOnce(`[protect] failed to apply loader: ${error}`);
+ }
+ }
+ }
+
+ // apply individual loader
+ applyLoader(loader: ProtectLoader) {
+ // we use rollout for percentage based rollouts (as the environment file is cached)
+ if (loader.rollout !== undefined) {
+ const rollout = loader.rollout;
+ if (typeof rollout !== 'number' || rollout < 0) {
+ // invalid rollout percentage - do nothing
+ logger.warnOnce(`[protect] loader rollout value is invalid: ${rollout}`);
+ return;
+ }
+ if (rollout === 0 || Math.random() > rollout) {
+ // not in rollout percentage - do nothing
+ return;
+ }
+ }
+
+ const type = loader.type || 'script';
+ const target = loader.target || 'body';
+
+ const element = document.createElement(type);
+
+ if (loader.attributes) {
+ for (const [key, value] of Object.entries(loader.attributes)) {
+ switch (typeof value) {
+ case 'string':
+ case 'number':
+ case 'boolean':
+ element.setAttribute(key, String(value));
+ break;
+ default:
+ // illegal to set.
+ logger.warnOnce(`[protect] loader attribute is invalid type: ${key}=${value}`);
+ break;
+ }
+ }
+ }
+
+ if (loader.textContent && typeof loader.textContent === 'string') {
+ element.textContent = loader.textContent;
+ }
+
+ switch (target) {
+ case 'head':
+ document.head.appendChild(element);
+ break;
+ case 'body':
+ document.body.appendChild(element);
+ break;
+ default:
+ if (target?.startsWith('#')) {
+ const targetElement = document.getElementById(target.substring(1));
+ if (!targetElement) {
+ logger.warnOnce(`[protect] loader target element not found: ${target}`);
+ return;
+ }
+ targetElement.appendChild(element);
+ return;
+ }
+ logger.warnOnce(`[protect] loader target is invalid: ${target}`);
+ break;
+ }
+ }
+}

packages/clerk-js/src/core/resources/Environment.ts

@@ -6,12 +6,13 @@ import type {
  EnvironmentJSONSnapshot,
  EnvironmentResource,
  OrganizationSettingsResource,
+ ProtectConfigResource,
  UserSettingsResource,
 } from '@clerk/shared/types';
 
 import { eventBus, events } from '../../core/events';
 import { APIKeySettings } from './APIKeySettings';
-import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, UserSettings } from './internal';
+import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, ProtectConfig, UserSettings } from './internal';
 import { OrganizationSettings } from './OrganizationSettings';
 
 export class Environment extends BaseResource implements EnvironmentResource {
@@ -26,6 +27,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  organizationSettings: OrganizationSettingsResource = new OrganizationSettings();
  commerceSettings: CommerceSettingsResource = new CommerceSettings();
  apiKeysSettings: APIKeySettings = new APIKeySettings();
+ protectConfig: ProtectConfigResource = new ProtectConfig();
 
  public static getInstance(): Environment {
  if (!Environment.instance) {
@@ -54,6 +56,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  this.userSettings = new UserSettings(data.user_settings);
  this.commerceSettings = new CommerceSettings(data.commerce_settings);
  this.apiKeysSettings = new APIKeySettings(data.api_keys_settings);
+ this.protectConfig = new ProtectConfig(data.protect_config);
 
  return this;
  }
@@ -95,6 +98,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  user_settings: this.userSettings.__internal_toSnapshot(),
  commerce_settings: this.commerceSettings.__internal_toSnapshot(),
  api_keys_settings: this.apiKeysSettings.__internal_toSnapshot(),
+ protect_config: this.protectConfig.__internal_toSnapshot(),
  };
  }
 }

packages/clerk-js/src/core/resources/ProtectConfig.ts

@@ -0,0 +1,39 @@
+import type {
+ ProtectConfigJSON,
+ ProtectConfigJSONSnapshot,
+ ProtectConfigResource,
+ ProtectLoader,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class ProtectConfig extends BaseResource implements ProtectConfigResource {
+ id: string = '';
+ loaders?: ProtectLoader[];
+ rollout?: number;
+
+ public constructor(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null = null) {
+ super();
+
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = this.withDefault(data.id, this.id);
+ this.loaders = this.withDefault(data.loaders, this.loaders);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): ProtectConfigJSONSnapshot {
+ return {
+ object: 'protect_config',
+ id: this.id,
+ loaders: this.loaders,
+ };
+ }
+}

packages/clerk-js/src/core/resources/internal.ts

@@ -29,6 +29,7 @@ export * from './OrganizationSuggestion';
 export * from './SamlAccount';
 export * from './Session';
 export * from './Passkey';
+export * from './ProtectConfig';
 export * from './PublicUserData';
 export * from './SessionWithActivities';
 export * from './SignIn';

packages/shared/src/types/environment.ts

@@ -3,6 +3,7 @@ import type { AuthConfigResource } from './authConfig';
 import type { CommerceSettingsResource } from './commerceSettings';
 import type { DisplayConfigResource } from './displayConfig';
 import type { OrganizationSettingsResource } from './organizationSettings';
+import type { ProtectConfigResource } from './protectConfig';
 import type { ClerkResource } from './resource';
 import type { EnvironmentJSONSnapshot } from './snapshots';
 import type { UserSettingsResource } from './userSettings';
@@ -14,6 +15,7 @@ export interface EnvironmentResource extends ClerkResource {
  displayConfig: DisplayConfigResource;
  commerceSettings: CommerceSettingsResource;
  apiKeysSettings: APIKeysSettingsResource;
+ protectConfig: ProtectConfigResource;
  isSingleSession: () => boolean;
  isProduction: () => boolean;
  isDevelopmentOrStaging: () => boolean;

packages/shared/src/types/index.ts

@@ -46,6 +46,7 @@ export type * from './permission';
 export type * from './phoneCodeChannel';
 export type * from './phoneNumber';
 export type * from './protect';
+export type * from './protectConfig';
 export type * from './redirects';
 export type * from './resource';
 export type * from './role';

packages/shared/src/types/json.ts

@@ -25,6 +25,7 @@ import type { OrganizationCustomRoleKey, OrganizationPermissionKey } from './org
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { OrganizationSuggestionStatus } from './organizationSuggestion';
 import type { PhoneCodeChannel } from './phoneCodeChannel';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SamlIdpSlug } from './saml';
 import type { SessionStatus, SessionTask } from './session';
 import type { SessionVerificationLevel, SessionVerificationStatus } from './sessionVerification';
@@ -90,6 +91,7 @@ export interface EnvironmentJSON extends ClerkResourceJSON {
  maintenance_mode: boolean;
  organization_settings: OrganizationSettingsJSON;
  user_settings: UserSettingsJSON;
+ protect_config: ProtectConfigJSON;
 }
 
 export type LastAuthenticationStrategy =

packages/shared/src/types/protectConfig.ts

@@ -0,0 +1,22 @@
+import type { ClerkResource } from './resource';
+import type { ProtectConfigJSONSnapshot } from './snapshots';
+
+export interface ProtectLoader {
+ rollout?: number;
+ target: 'head' | 'body' | `#${string}`;
+ type: string;
+ attributes?: Record<string, string | number | boolean>;
+ textContent?: string;
+}
+
+export interface ProtectConfigJSON {
+ object: 'protect_config';
+ id: string;
+ loaders?: ProtectLoader[];
+}
+
+export interface ProtectConfigResource extends ClerkResource {
+ id: string;
+ loaders?: ProtectLoader[];
+ __internal_toSnapshot: () => ProtectConfigJSONSnapshot;
+}

packages/shared/src/types/snapshots.ts

@@ -31,6 +31,7 @@ import type {
  Web3WalletJSON,
 } from './json';
 import type { OrganizationSettingsJSON } from './organizationSettings';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SignInJSON } from './signIn';
 import type { UserSettingsJSON } from './userSettings';
 import type { Nullable, Override } from './utils';
@@ -119,6 +120,8 @@ export type EnvironmentJSONSnapshot = EnvironmentJSON;
 
 export type DisplayConfigJSONSnapshot = DisplayConfigJSON;
 
+export type ProtectConfigJSONSnapshot = ProtectConfigJSON;
+
 export type EmailAddressJSONSnapshot = Override<
  EmailAddressJSON,
  {

.changeset/beige-sloths-provide.md

@@ -0,0 +1,6 @@
+---
+"@clerk/clerk-js": minor
+"@clerk/shared": minor
+---
+
+Introduce ProtectConfig resource and Protect loader integration.

integration/tests/protect-service.test.ts

@@ -0,0 +1,76 @@
+import type { ProtectConfigJSON } from '@clerk/shared/types';
+import type { Page } from '@playwright/test';
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../presets';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+const mockProtectSettings = async (page: Page, config?: ProtectConfigJSON) => {
+ await page.route('*/**/v1/environment*', async route => {
+ const response = await route.fetch();
+ const json = await response.json();
+ const newJson = {
+ ...json,
+ ...(config ? { protect_config: config } : {}),
+ };
+ await route.fulfill({ response, json: newJson });
+ });
+};
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('Clerk Protect checks @generic', ({ app }) => {
+ test.describe.configure({ mode: 'parallel' });
+
+ test.afterAll(async () => {
+ await app.teardown();
+ });
+
+ test('should add loader script when protect_config.loader is set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 1.0,
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-1', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-1')).toHaveAttribute('type', 'module');
+ });
+
+ test('should not add loader script when protect_config.loader is set and rollout 0.00', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 0, // force 0% rollout, should not materialize
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-2', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-2')).toHaveCount(0);
+ });
+
+ test('should not create loader element when protect_config.loader is not set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page);
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ // Playwright locators are always objects, never undefined
+ await expect(page.locator('#test-protect-loader')).toHaveCount(0);
+ });
+});

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.channel.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "65KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },

packages/clerk-js/src/core/clerk.ts

@@ -158,6 +158,7 @@ import { createClientFromJwt } from './jwt-client';
 import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
+import { Protect } from './protect';
 import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
 import { getTaskEndpoint, navigateIfTaskExists, warnMissingPendingTaskHandlers } from './sessionTasks';
 import { State } from './state';
@@ -227,6 +228,7 @@ export class Clerk implements ClerkInterface {
  #domain: DomainOrProxyUrl['domain'];
  #proxyUrl: DomainOrProxyUrl['proxyUrl'];
  #authService?: AuthCookieService;
+ #protect?: Protect;
  #captchaHeartbeat?: CaptchaHeartbeat;
  #broadcastChannel: BroadcastChannel | null = null;
  #componentControls?: ReturnType<MountComponentRenderer> | null;
@@ -429,6 +431,7 @@ export class Clerk implements ClerkInterface {
 
  // This line is used for the piggy-backing mechanism
  BaseResource.clerk = this;
+ this.#protect = new Protect();
  }
 
  public getFapiClient = (): FapiClient => this.#fapiClient;
@@ -516,6 +519,7 @@ export class Clerk implements ClerkInterface {
  ...(telemetryEnabled && this.telemetry ? { telemetryCollector: this.telemetry } : {}),
  });
  }
+ this.#protect?.load(this.environment as Environment);
  debugLogger.info('load() complete', {}, 'clerk');
  } catch (error) {
  this.#publicEventBus.emit(clerkEvents.Status, 'error');

packages/clerk-js/src/core/protect.ts

@@ -0,0 +1,97 @@
+import { inBrowser } from '@clerk/shared/browser';
+import { logger } from '@clerk/shared/logger';
+import type { ProtectLoader } from '@clerk/shared/types';
+
+import type { Environment } from './resources';
+export class Protect {
+ #initialized: boolean = false;
+
+ load(env: Environment): void {
+ const config = env?.protectConfig;
+
+ if (!config?.loaders || !Array.isArray(config.loaders) || config.loaders.length === 0) {
+ // not enabled or no protect config available
+ return;
+ } else if (this.#initialized) {
+ // already initialized - do nothing
+ return;
+ } else if (!inBrowser()) {
+ // no document: not running browser?
+ return;
+ }
+
+ // here rather than at end to mark as initialized even if load fails.
+ this.#initialized = true;
+
+ for (const loader of config.loaders) {
+ try {
+ this.applyLoader(loader);
+ } catch (error) {
+ logger.warnOnce(`[protect] failed to apply loader: ${error}`);
+ }
+ }
+ }
+
+ // apply individual loader
+ applyLoader(loader: ProtectLoader) {
+ // we use rollout for percentage based rollouts (as the environment file is cached)
+ if (loader.rollout !== undefined) {
+ const rollout = loader.rollout;
+ if (typeof rollout !== 'number' || rollout < 0) {
+ // invalid rollout percentage - do nothing
+ logger.warnOnce(`[protect] loader rollout value is invalid: ${rollout}`);
+ return;
+ }
+ if (rollout === 0 || Math.random() > rollout) {
+ // not in rollout percentage - do nothing
+ return;
+ }
+ }
+
+ const type = loader.type || 'script';
+ const target = loader.target || 'body';
+
+ const element = document.createElement(type);
+
+ if (loader.attributes) {
+ for (const [key, value] of Object.entries(loader.attributes)) {
+ switch (typeof value) {
+ case 'string':
+ case 'number':
+ case 'boolean':
+ element.setAttribute(key, String(value));
+ break;
+ default:
+ // illegal to set.
+ logger.warnOnce(`[protect] loader attribute is invalid type: ${key}=${value}`);
+ break;
+ }
+ }
+ }
+
+ if (loader.textContent && typeof loader.textContent === 'string') {
+ element.textContent = loader.textContent;
+ }
+
+ switch (target) {
+ case 'head':
+ document.head.appendChild(element);
+ break;
+ case 'body':
+ document.body.appendChild(element);
+ break;
+ default:
+ if (target?.startsWith('#')) {
+ const targetElement = document.getElementById(target.substring(1));
+ if (!targetElement) {
+ logger.warnOnce(`[protect] loader target element not found: ${target}`);
+ return;
+ }
+ targetElement.appendChild(element);
+ return;
+ }
+ logger.warnOnce(`[protect] loader target is invalid: ${target}`);
+ break;
+ }
+ }
+}

packages/clerk-js/src/core/resources/Environment.ts

@@ -6,12 +6,13 @@ import type {
  EnvironmentJSONSnapshot,
  EnvironmentResource,
  OrganizationSettingsResource,
+ ProtectConfigResource,
  UserSettingsResource,
 } from '@clerk/shared/types';
 
 import { eventBus, events } from '../../core/events';
 import { APIKeySettings } from './APIKeySettings';
-import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, UserSettings } from './internal';
+import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, ProtectConfig, UserSettings } from './internal';
 import { OrganizationSettings } from './OrganizationSettings';
 
 export class Environment extends BaseResource implements EnvironmentResource {
@@ -26,6 +27,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  organizationSettings: OrganizationSettingsResource = new OrganizationSettings();
  commerceSettings: CommerceSettingsResource = new CommerceSettings();
  apiKeysSettings: APIKeySettings = new APIKeySettings();
+ protectConfig: ProtectConfigResource = new ProtectConfig();
 
  public static getInstance(): Environment {
  if (!Environment.instance) {
@@ -54,6 +56,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  this.userSettings = new UserSettings(data.user_settings);
  this.commerceSettings = new CommerceSettings(data.commerce_settings);
  this.apiKeysSettings = new APIKeySettings(data.api_keys_settings);
+ this.protectConfig = new ProtectConfig(data.protect_config);
 
  return this;
  }
@@ -95,6 +98,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  user_settings: this.userSettings.__internal_toSnapshot(),
  commerce_settings: this.commerceSettings.__internal_toSnapshot(),
  api_keys_settings: this.apiKeysSettings.__internal_toSnapshot(),
+ protect_config: this.protectConfig.__internal_toSnapshot(),
  };
  }
 }

packages/clerk-js/src/core/resources/ProtectConfig.ts

@@ -0,0 +1,39 @@
+import type {
+ ProtectConfigJSON,
+ ProtectConfigJSONSnapshot,
+ ProtectConfigResource,
+ ProtectLoader,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class ProtectConfig extends BaseResource implements ProtectConfigResource {
+ id: string = '';
+ loaders?: ProtectLoader[];
+ rollout?: number;
+
+ public constructor(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null = null) {
+ super();
+
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = this.withDefault(data.id, this.id);
+ this.loaders = this.withDefault(data.loaders, this.loaders);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): ProtectConfigJSONSnapshot {
+ return {
+ object: 'protect_config',
+ id: this.id,
+ loaders: this.loaders,
+ };
+ }
+}

packages/clerk-js/src/core/resources/internal.ts

@@ -29,6 +29,7 @@ export * from './OrganizationSuggestion';
 export * from './SamlAccount';
 export * from './Session';
 export * from './Passkey';
+export * from './ProtectConfig';
 export * from './PublicUserData';
 export * from './SessionWithActivities';
 export * from './SignIn';

packages/shared/src/types/environment.ts

@@ -3,6 +3,7 @@ import type { AuthConfigResource } from './authConfig';
 import type { CommerceSettingsResource } from './commerceSettings';
 import type { DisplayConfigResource } from './displayConfig';
 import type { OrganizationSettingsResource } from './organizationSettings';
+import type { ProtectConfigResource } from './protectConfig';
 import type { ClerkResource } from './resource';
 import type { EnvironmentJSONSnapshot } from './snapshots';
 import type { UserSettingsResource } from './userSettings';
@@ -14,6 +15,7 @@ export interface EnvironmentResource extends ClerkResource {
  displayConfig: DisplayConfigResource;
  commerceSettings: CommerceSettingsResource;
  apiKeysSettings: APIKeysSettingsResource;
+ protectConfig: ProtectConfigResource;
  isSingleSession: () => boolean;
  isProduction: () => boolean;
  isDevelopmentOrStaging: () => boolean;

packages/shared/src/types/index.ts

@@ -46,6 +46,7 @@ export type * from './permission';
 export type * from './phoneCodeChannel';
 export type * from './phoneNumber';
 export type * from './protect';
+export type * from './protectConfig';
 export type * from './redirects';
 export type * from './resource';
 export type * from './role';

packages/shared/src/types/json.ts

@@ -25,6 +25,7 @@ import type { OrganizationCustomRoleKey, OrganizationPermissionKey } from './org
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { OrganizationSuggestionStatus } from './organizationSuggestion';
 import type { PhoneCodeChannel } from './phoneCodeChannel';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SamlIdpSlug } from './saml';
 import type { SessionStatus, SessionTask } from './session';
 import type { SessionVerificationLevel, SessionVerificationStatus } from './sessionVerification';
@@ -90,6 +91,7 @@ export interface EnvironmentJSON extends ClerkResourceJSON {
  maintenance_mode: boolean;
  organization_settings: OrganizationSettingsJSON;
  user_settings: UserSettingsJSON;
+ protect_config: ProtectConfigJSON;
 }
 
 export type LastAuthenticationStrategy =

packages/shared/src/types/protectConfig.ts

@@ -0,0 +1,22 @@
+import type { ClerkResource } from './resource';
+import type { ProtectConfigJSONSnapshot } from './snapshots';
+
+export interface ProtectLoader {
+ rollout?: number;
+ target: 'head' | 'body' | `#${string}`;
+ type: string;
+ attributes?: Record<string, string | number | boolean>;
+ textContent?: string;
+}
+
+export interface ProtectConfigJSON {
+ object: 'protect_config';
+ id: string;
+ loaders?: ProtectLoader[];
+}
+
+export interface ProtectConfigResource extends ClerkResource {
+ id: string;
+ loaders?: ProtectLoader[];
+ __internal_toSnapshot: () => ProtectConfigJSONSnapshot;
+}

packages/shared/src/types/snapshots.ts

@@ -31,6 +31,7 @@ import type {
  Web3WalletJSON,
 } from './json';
 import type { OrganizationSettingsJSON } from './organizationSettings';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SignInJSON } from './signIn';
 import type { UserSettingsJSON } from './userSettings';
 import type { Nullable, Override } from './utils';
@@ -119,6 +120,8 @@ export type EnvironmentJSONSnapshot = EnvironmentJSON;
 
 export type DisplayConfigJSONSnapshot = DisplayConfigJSON;
 
+export type ProtectConfigJSONSnapshot = ProtectConfigJSON;
+
 export type EmailAddressJSONSnapshot = Override<
  EmailAddressJSON,
  {

.changeset/beige-sloths-provide.md

@@ -0,0 +1,6 @@
+---
+"@clerk/clerk-js": minor
+"@clerk/shared": minor
+---
+
+Introduce ProtectConfig resource and Protect loader integration.

integration/tests/protect-service.test.ts

@@ -0,0 +1,76 @@
+import type { ProtectConfigJSON } from '@clerk/shared/types';
+import type { Page } from '@playwright/test';
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../presets';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+const mockProtectSettings = async (page: Page, config?: ProtectConfigJSON) => {
+ await page.route('*/**/v1/environment*', async route => {
+ const response = await route.fetch();
+ const json = await response.json();
+ const newJson = {
+ ...json,
+ ...(config ? { protect_config: config } : {}),
+ };
+ await route.fulfill({ response, json: newJson });
+ });
+};
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('Clerk Protect checks @generic', ({ app }) => {
+ test.describe.configure({ mode: 'parallel' });
+
+ test.afterAll(async () => {
+ await app.teardown();
+ });
+
+ test('should add loader script when protect_config.loader is set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 1.0,
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-1', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-1')).toHaveAttribute('type', 'module');
+ });
+
+ test('should not add loader script when protect_config.loader is set and rollout 0.00', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 0, // force 0% rollout, should not materialize
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-2', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-2')).toHaveCount(0);
+ });
+
+ test('should not create loader element when protect_config.loader is not set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page);
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ // Playwright locators are always objects, never undefined
+ await expect(page.locator('#test-protect-loader')).toHaveCount(0);
+ });
+});

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.channel.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "65KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },

packages/clerk-js/src/core/clerk.ts

@@ -158,6 +158,7 @@ import { createClientFromJwt } from './jwt-client';
 import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
+import { Protect } from './protect';
 import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
 import { getTaskEndpoint, navigateIfTaskExists, warnMissingPendingTaskHandlers } from './sessionTasks';
 import { State } from './state';
@@ -227,6 +228,7 @@ export class Clerk implements ClerkInterface {
  #domain: DomainOrProxyUrl['domain'];
  #proxyUrl: DomainOrProxyUrl['proxyUrl'];
  #authService?: AuthCookieService;
+ #protect?: Protect;
  #captchaHeartbeat?: CaptchaHeartbeat;
  #broadcastChannel: BroadcastChannel | null = null;
  #componentControls?: ReturnType<MountComponentRenderer> | null;
@@ -429,6 +431,7 @@ export class Clerk implements ClerkInterface {
 
  // This line is used for the piggy-backing mechanism
  BaseResource.clerk = this;
+ this.#protect = new Protect();
  }
 
  public getFapiClient = (): FapiClient => this.#fapiClient;
@@ -516,6 +519,7 @@ export class Clerk implements ClerkInterface {
  ...(telemetryEnabled && this.telemetry ? { telemetryCollector: this.telemetry } : {}),
  });
  }
+ this.#protect?.load(this.environment as Environment);
  debugLogger.info('load() complete', {}, 'clerk');
  } catch (error) {
  this.#publicEventBus.emit(clerkEvents.Status, 'error');

packages/clerk-js/src/core/protect.ts

@@ -0,0 +1,97 @@
+import { inBrowser } from '@clerk/shared/browser';
+import { logger } from '@clerk/shared/logger';
+import type { ProtectLoader } from '@clerk/shared/types';
+
+import type { Environment } from './resources';
+export class Protect {
+ #initialized: boolean = false;
+
+ load(env: Environment): void {
+ const config = env?.protectConfig;
+
+ if (!config?.loaders || !Array.isArray(config.loaders) || config.loaders.length === 0) {
+ // not enabled or no protect config available
+ return;
+ } else if (this.#initialized) {
+ // already initialized - do nothing
+ return;
+ } else if (!inBrowser()) {
+ // no document: not running browser?
+ return;
+ }
+
+ // here rather than at end to mark as initialized even if load fails.
+ this.#initialized = true;
+
+ for (const loader of config.loaders) {
+ try {
+ this.applyLoader(loader);
+ } catch (error) {
+ logger.warnOnce(`[protect] failed to apply loader: ${error}`);
+ }
+ }
+ }
+
+ // apply individual loader
+ applyLoader(loader: ProtectLoader) {
+ // we use rollout for percentage based rollouts (as the environment file is cached)
+ if (loader.rollout !== undefined) {
+ const rollout = loader.rollout;
+ if (typeof rollout !== 'number' || rollout < 0) {
+ // invalid rollout percentage - do nothing
+ logger.warnOnce(`[protect] loader rollout value is invalid: ${rollout}`);
+ return;
+ }
+ if (rollout === 0 || Math.random() > rollout) {
+ // not in rollout percentage - do nothing
+ return;
+ }
+ }
+
+ const type = loader.type || 'script';
+ const target = loader.target || 'body';
+
+ const element = document.createElement(type);
+
+ if (loader.attributes) {
+ for (const [key, value] of Object.entries(loader.attributes)) {
+ switch (typeof value) {
+ case 'string':
+ case 'number':
+ case 'boolean':
+ element.setAttribute(key, String(value));
+ break;
+ default:
+ // illegal to set.
+ logger.warnOnce(`[protect] loader attribute is invalid type: ${key}=${value}`);
+ break;
+ }
+ }
+ }
+
+ if (loader.textContent && typeof loader.textContent === 'string') {
+ element.textContent = loader.textContent;
+ }
+
+ switch (target) {
+ case 'head':
+ document.head.appendChild(element);
+ break;
+ case 'body':
+ document.body.appendChild(element);
+ break;
+ default:
+ if (target?.startsWith('#')) {
+ const targetElement = document.getElementById(target.substring(1));
+ if (!targetElement) {
+ logger.warnOnce(`[protect] loader target element not found: ${target}`);
+ return;
+ }
+ targetElement.appendChild(element);
+ return;
+ }
+ logger.warnOnce(`[protect] loader target is invalid: ${target}`);
+ break;
+ }
+ }
+}

packages/clerk-js/src/core/resources/Environment.ts

@@ -6,12 +6,13 @@ import type {
  EnvironmentJSONSnapshot,
  EnvironmentResource,
  OrganizationSettingsResource,
+ ProtectConfigResource,
  UserSettingsResource,
 } from '@clerk/shared/types';
 
 import { eventBus, events } from '../../core/events';
 import { APIKeySettings } from './APIKeySettings';
-import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, UserSettings } from './internal';
+import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, ProtectConfig, UserSettings } from './internal';
 import { OrganizationSettings } from './OrganizationSettings';
 
 export class Environment extends BaseResource implements EnvironmentResource {
@@ -26,6 +27,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  organizationSettings: OrganizationSettingsResource = new OrganizationSettings();
  commerceSettings: CommerceSettingsResource = new CommerceSettings();
  apiKeysSettings: APIKeySettings = new APIKeySettings();
+ protectConfig: ProtectConfigResource = new ProtectConfig();
 
  public static getInstance(): Environment {
  if (!Environment.instance) {
@@ -54,6 +56,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  this.userSettings = new UserSettings(data.user_settings);
  this.commerceSettings = new CommerceSettings(data.commerce_settings);
  this.apiKeysSettings = new APIKeySettings(data.api_keys_settings);
+ this.protectConfig = new ProtectConfig(data.protect_config);
 
  return this;
  }
@@ -95,6 +98,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  user_settings: this.userSettings.__internal_toSnapshot(),
  commerce_settings: this.commerceSettings.__internal_toSnapshot(),
  api_keys_settings: this.apiKeysSettings.__internal_toSnapshot(),
+ protect_config: this.protectConfig.__internal_toSnapshot(),
  };
  }
 }

packages/clerk-js/src/core/resources/ProtectConfig.ts

@@ -0,0 +1,39 @@
+import type {
+ ProtectConfigJSON,
+ ProtectConfigJSONSnapshot,
+ ProtectConfigResource,
+ ProtectLoader,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class ProtectConfig extends BaseResource implements ProtectConfigResource {
+ id: string = '';
+ loaders?: ProtectLoader[];
+ rollout?: number;
+
+ public constructor(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null = null) {
+ super();
+
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = this.withDefault(data.id, this.id);
+ this.loaders = this.withDefault(data.loaders, this.loaders);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): ProtectConfigJSONSnapshot {
+ return {
+ object: 'protect_config',
+ id: this.id,
+ loaders: this.loaders,
+ };
+ }
+}

packages/clerk-js/src/core/resources/internal.ts

@@ -29,6 +29,7 @@ export * from './OrganizationSuggestion';
 export * from './SamlAccount';
 export * from './Session';
 export * from './Passkey';
+export * from './ProtectConfig';
 export * from './PublicUserData';
 export * from './SessionWithActivities';
 export * from './SignIn';

packages/shared/src/types/environment.ts

@@ -3,6 +3,7 @@ import type { AuthConfigResource } from './authConfig';
 import type { CommerceSettingsResource } from './commerceSettings';
 import type { DisplayConfigResource } from './displayConfig';
 import type { OrganizationSettingsResource } from './organizationSettings';
+import type { ProtectConfigResource } from './protectConfig';
 import type { ClerkResource } from './resource';
 import type { EnvironmentJSONSnapshot } from './snapshots';
 import type { UserSettingsResource } from './userSettings';
@@ -14,6 +15,7 @@ export interface EnvironmentResource extends ClerkResource {
  displayConfig: DisplayConfigResource;
  commerceSettings: CommerceSettingsResource;
  apiKeysSettings: APIKeysSettingsResource;
+ protectConfig: ProtectConfigResource;
  isSingleSession: () => boolean;
  isProduction: () => boolean;
  isDevelopmentOrStaging: () => boolean;

packages/shared/src/types/index.ts

@@ -46,6 +46,7 @@ export type * from './permission';
 export type * from './phoneCodeChannel';
 export type * from './phoneNumber';
 export type * from './protect';
+export type * from './protectConfig';
 export type * from './redirects';
 export type * from './resource';
 export type * from './role';

packages/shared/src/types/json.ts

@@ -25,6 +25,7 @@ import type { OrganizationCustomRoleKey, OrganizationPermissionKey } from './org
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { OrganizationSuggestionStatus } from './organizationSuggestion';
 import type { PhoneCodeChannel } from './phoneCodeChannel';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SamlIdpSlug } from './saml';
 import type { SessionStatus, SessionTask } from './session';
 import type { SessionVerificationLevel, SessionVerificationStatus } from './sessionVerification';
@@ -90,6 +91,7 @@ export interface EnvironmentJSON extends ClerkResourceJSON {
  maintenance_mode: boolean;
  organization_settings: OrganizationSettingsJSON;
  user_settings: UserSettingsJSON;
+ protect_config: ProtectConfigJSON;
 }
 
 export type LastAuthenticationStrategy =

packages/shared/src/types/protectConfig.ts

@@ -0,0 +1,22 @@
+import type { ClerkResource } from './resource';
+import type { ProtectConfigJSONSnapshot } from './snapshots';
+
+export interface ProtectLoader {
+ rollout?: number;
+ target: 'head' | 'body' | `#${string}`;
+ type: string;
+ attributes?: Record<string, string | number | boolean>;
+ textContent?: string;
+}
+
+export interface ProtectConfigJSON {
+ object: 'protect_config';
+ id: string;
+ loaders?: ProtectLoader[];
+}
+
+export interface ProtectConfigResource extends ClerkResource {
+ id: string;
+ loaders?: ProtectLoader[];
+ __internal_toSnapshot: () => ProtectConfigJSONSnapshot;
+}

packages/shared/src/types/snapshots.ts

@@ -31,6 +31,7 @@ import type {
  Web3WalletJSON,
 } from './json';
 import type { OrganizationSettingsJSON } from './organizationSettings';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SignInJSON } from './signIn';
 import type { UserSettingsJSON } from './userSettings';
 import type { Nullable, Override } from './utils';
@@ -119,6 +120,8 @@ export type EnvironmentJSONSnapshot = EnvironmentJSON;
 
 export type DisplayConfigJSONSnapshot = DisplayConfigJSON;
 
+export type ProtectConfigJSONSnapshot = ProtectConfigJSON;
+
 export type EmailAddressJSONSnapshot = Override<
  EmailAddressJSON,
  {

.changeset/beige-sloths-provide.md

@@ -0,0 +1,6 @@
+---
+"@clerk/clerk-js": minor
+"@clerk/shared": minor
+---
+
+Introduce ProtectConfig resource and Protect loader integration.

integration/tests/protect-service.test.ts

@@ -0,0 +1,76 @@
+import type { ProtectConfigJSON } from '@clerk/shared/types';
+import type { Page } from '@playwright/test';
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../presets';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+const mockProtectSettings = async (page: Page, config?: ProtectConfigJSON) => {
+ await page.route('*/**/v1/environment*', async route => {
+ const response = await route.fetch();
+ const json = await response.json();
+ const newJson = {
+ ...json,
+ ...(config ? { protect_config: config } : {}),
+ };
+ await route.fulfill({ response, json: newJson });
+ });
+};
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('Clerk Protect checks @generic', ({ app }) => {
+ test.describe.configure({ mode: 'parallel' });
+
+ test.afterAll(async () => {
+ await app.teardown();
+ });
+
+ test('should add loader script when protect_config.loader is set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 1.0,
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-1', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-1')).toHaveAttribute('type', 'module');
+ });
+
+ test('should not add loader script when protect_config.loader is set and rollout 0.00', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 0, // force 0% rollout, should not materialize
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-2', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-2')).toHaveCount(0);
+ });
+
+ test('should not create loader element when protect_config.loader is not set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page);
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ // Playwright locators are always objects, never undefined
+ await expect(page.locator('#test-protect-loader')).toHaveCount(0);
+ });
+});

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.channel.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "65KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },

packages/clerk-js/src/core/clerk.ts

@@ -158,6 +158,7 @@ import { createClientFromJwt } from './jwt-client';
 import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
+import { Protect } from './protect';
 import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
 import { getTaskEndpoint, navigateIfTaskExists, warnMissingPendingTaskHandlers } from './sessionTasks';
 import { State } from './state';
@@ -227,6 +228,7 @@ export class Clerk implements ClerkInterface {
  #domain: DomainOrProxyUrl['domain'];
  #proxyUrl: DomainOrProxyUrl['proxyUrl'];
  #authService?: AuthCookieService;
+ #protect?: Protect;
  #captchaHeartbeat?: CaptchaHeartbeat;
  #broadcastChannel: BroadcastChannel | null = null;
  #componentControls?: ReturnType<MountComponentRenderer> | null;
@@ -429,6 +431,7 @@ export class Clerk implements ClerkInterface {
 
  // This line is used for the piggy-backing mechanism
  BaseResource.clerk = this;
+ this.#protect = new Protect();
  }
 
  public getFapiClient = (): FapiClient => this.#fapiClient;
@@ -516,6 +519,7 @@ export class Clerk implements ClerkInterface {
  ...(telemetryEnabled && this.telemetry ? { telemetryCollector: this.telemetry } : {}),
  });
  }
+ this.#protect?.load(this.environment as Environment);
  debugLogger.info('load() complete', {}, 'clerk');
  } catch (error) {
  this.#publicEventBus.emit(clerkEvents.Status, 'error');

packages/clerk-js/src/core/protect.ts

@@ -0,0 +1,97 @@
+import { inBrowser } from '@clerk/shared/browser';
+import { logger } from '@clerk/shared/logger';
+import type { ProtectLoader } from '@clerk/shared/types';
+
+import type { Environment } from './resources';
+export class Protect {
+ #initialized: boolean = false;
+
+ load(env: Environment): void {
+ const config = env?.protectConfig;
+
+ if (!config?.loaders || !Array.isArray(config.loaders) || config.loaders.length === 0) {
+ // not enabled or no protect config available
+ return;
+ } else if (this.#initialized) {
+ // already initialized - do nothing
+ return;
+ } else if (!inBrowser()) {
+ // no document: not running browser?
+ return;
+ }
+
+ // here rather than at end to mark as initialized even if load fails.
+ this.#initialized = true;
+
+ for (const loader of config.loaders) {
+ try {
+ this.applyLoader(loader);
+ } catch (error) {
+ logger.warnOnce(`[protect] failed to apply loader: ${error}`);
+ }
+ }
+ }
+
+ // apply individual loader
+ applyLoader(loader: ProtectLoader) {
+ // we use rollout for percentage based rollouts (as the environment file is cached)
+ if (loader.rollout !== undefined) {
+ const rollout = loader.rollout;
+ if (typeof rollout !== 'number' || rollout < 0) {
+ // invalid rollout percentage - do nothing
+ logger.warnOnce(`[protect] loader rollout value is invalid: ${rollout}`);
+ return;
+ }
+ if (rollout === 0 || Math.random() > rollout) {
+ // not in rollout percentage - do nothing
+ return;
+ }
+ }
+
+ const type = loader.type || 'script';
+ const target = loader.target || 'body';
+
+ const element = document.createElement(type);
+
+ if (loader.attributes) {
+ for (const [key, value] of Object.entries(loader.attributes)) {
+ switch (typeof value) {
+ case 'string':
+ case 'number':
+ case 'boolean':
+ element.setAttribute(key, String(value));
+ break;
+ default:
+ // illegal to set.
+ logger.warnOnce(`[protect] loader attribute is invalid type: ${key}=${value}`);
+ break;
+ }
+ }
+ }
+
+ if (loader.textContent && typeof loader.textContent === 'string') {
+ element.textContent = loader.textContent;
+ }
+
+ switch (target) {
+ case 'head':
+ document.head.appendChild(element);
+ break;
+ case 'body':
+ document.body.appendChild(element);
+ break;
+ default:
+ if (target?.startsWith('#')) {
+ const targetElement = document.getElementById(target.substring(1));
+ if (!targetElement) {
+ logger.warnOnce(`[protect] loader target element not found: ${target}`);
+ return;
+ }
+ targetElement.appendChild(element);
+ return;
+ }
+ logger.warnOnce(`[protect] loader target is invalid: ${target}`);
+ break;
+ }
+ }
+}

packages/clerk-js/src/core/resources/Environment.ts

@@ -6,12 +6,13 @@ import type {
  EnvironmentJSONSnapshot,
  EnvironmentResource,
  OrganizationSettingsResource,
+ ProtectConfigResource,
  UserSettingsResource,
 } from '@clerk/shared/types';
 
 import { eventBus, events } from '../../core/events';
 import { APIKeySettings } from './APIKeySettings';
-import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, UserSettings } from './internal';
+import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, ProtectConfig, UserSettings } from './internal';
 import { OrganizationSettings } from './OrganizationSettings';
 
 export class Environment extends BaseResource implements EnvironmentResource {
@@ -26,6 +27,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  organizationSettings: OrganizationSettingsResource = new OrganizationSettings();
  commerceSettings: CommerceSettingsResource = new CommerceSettings();
  apiKeysSettings: APIKeySettings = new APIKeySettings();
+ protectConfig: ProtectConfigResource = new ProtectConfig();
 
  public static getInstance(): Environment {
  if (!Environment.instance) {
@@ -54,6 +56,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  this.userSettings = new UserSettings(data.user_settings);
  this.commerceSettings = new CommerceSettings(data.commerce_settings);
  this.apiKeysSettings = new APIKeySettings(data.api_keys_settings);
+ this.protectConfig = new ProtectConfig(data.protect_config);
 
  return this;
  }
@@ -95,6 +98,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  user_settings: this.userSettings.__internal_toSnapshot(),
  commerce_settings: this.commerceSettings.__internal_toSnapshot(),
  api_keys_settings: this.apiKeysSettings.__internal_toSnapshot(),
+ protect_config: this.protectConfig.__internal_toSnapshot(),
  };
  }
 }

packages/clerk-js/src/core/resources/ProtectConfig.ts

@@ -0,0 +1,39 @@
+import type {
+ ProtectConfigJSON,
+ ProtectConfigJSONSnapshot,
+ ProtectConfigResource,
+ ProtectLoader,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class ProtectConfig extends BaseResource implements ProtectConfigResource {
+ id: string = '';
+ loaders?: ProtectLoader[];
+ rollout?: number;
+
+ public constructor(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null = null) {
+ super();
+
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = this.withDefault(data.id, this.id);
+ this.loaders = this.withDefault(data.loaders, this.loaders);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): ProtectConfigJSONSnapshot {
+ return {
+ object: 'protect_config',
+ id: this.id,
+ loaders: this.loaders,
+ };
+ }
+}

packages/clerk-js/src/core/resources/internal.ts

@@ -29,6 +29,7 @@ export * from './OrganizationSuggestion';
 export * from './SamlAccount';
 export * from './Session';
 export * from './Passkey';
+export * from './ProtectConfig';
 export * from './PublicUserData';
 export * from './SessionWithActivities';
 export * from './SignIn';

packages/shared/src/types/environment.ts

@@ -3,6 +3,7 @@ import type { AuthConfigResource } from './authConfig';
 import type { CommerceSettingsResource } from './commerceSettings';
 import type { DisplayConfigResource } from './displayConfig';
 import type { OrganizationSettingsResource } from './organizationSettings';
+import type { ProtectConfigResource } from './protectConfig';
 import type { ClerkResource } from './resource';
 import type { EnvironmentJSONSnapshot } from './snapshots';
 import type { UserSettingsResource } from './userSettings';
@@ -14,6 +15,7 @@ export interface EnvironmentResource extends ClerkResource {
  displayConfig: DisplayConfigResource;
  commerceSettings: CommerceSettingsResource;
  apiKeysSettings: APIKeysSettingsResource;
+ protectConfig: ProtectConfigResource;
  isSingleSession: () => boolean;
  isProduction: () => boolean;
  isDevelopmentOrStaging: () => boolean;

packages/shared/src/types/index.ts

@@ -46,6 +46,7 @@ export type * from './permission';
 export type * from './phoneCodeChannel';
 export type * from './phoneNumber';
 export type * from './protect';
+export type * from './protectConfig';
 export type * from './redirects';
 export type * from './resource';
 export type * from './role';

packages/shared/src/types/json.ts

@@ -25,6 +25,7 @@ import type { OrganizationCustomRoleKey, OrganizationPermissionKey } from './org
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { OrganizationSuggestionStatus } from './organizationSuggestion';
 import type { PhoneCodeChannel } from './phoneCodeChannel';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SamlIdpSlug } from './saml';
 import type { SessionStatus, SessionTask } from './session';
 import type { SessionVerificationLevel, SessionVerificationStatus } from './sessionVerification';
@@ -90,6 +91,7 @@ export interface EnvironmentJSON extends ClerkResourceJSON {
  maintenance_mode: boolean;
  organization_settings: OrganizationSettingsJSON;
  user_settings: UserSettingsJSON;
+ protect_config: ProtectConfigJSON;
 }
 
 export type LastAuthenticationStrategy =

packages/shared/src/types/protectConfig.ts

@@ -0,0 +1,22 @@
+import type { ClerkResource } from './resource';
+import type { ProtectConfigJSONSnapshot } from './snapshots';
+
+export interface ProtectLoader {
+ rollout?: number;
+ target: 'head' | 'body' | `#${string}`;
+ type: string;
+ attributes?: Record<string, string | number | boolean>;
+ textContent?: string;
+}
+
+export interface ProtectConfigJSON {
+ object: 'protect_config';
+ id: string;
+ loaders?: ProtectLoader[];
+}
+
+export interface ProtectConfigResource extends ClerkResource {
+ id: string;
+ loaders?: ProtectLoader[];
+ __internal_toSnapshot: () => ProtectConfigJSONSnapshot;
+}

packages/shared/src/types/snapshots.ts

@@ -31,6 +31,7 @@ import type {
  Web3WalletJSON,
 } from './json';
 import type { OrganizationSettingsJSON } from './organizationSettings';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SignInJSON } from './signIn';
 import type { UserSettingsJSON } from './userSettings';
 import type { Nullable, Override } from './utils';
@@ -119,6 +120,8 @@ export type EnvironmentJSONSnapshot = EnvironmentJSON;
 
 export type DisplayConfigJSONSnapshot = DisplayConfigJSON;
 
+export type ProtectConfigJSONSnapshot = ProtectConfigJSON;
+
 export type EmailAddressJSONSnapshot = Override<
  EmailAddressJSON,
  {

.changeset/beige-sloths-provide.md

@@ -0,0 +1,6 @@
+---
+"@clerk/clerk-js": minor
+"@clerk/shared": minor
+---
+
+Introduce ProtectConfig resource and Protect loader integration.

integration/tests/protect-service.test.ts

@@ -0,0 +1,76 @@
+import type { ProtectConfigJSON } from '@clerk/shared/types';
+import type { Page } from '@playwright/test';
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../presets';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+const mockProtectSettings = async (page: Page, config?: ProtectConfigJSON) => {
+ await page.route('*/**/v1/environment*', async route => {
+ const response = await route.fetch();
+ const json = await response.json();
+ const newJson = {
+ ...json,
+ ...(config ? { protect_config: config } : {}),
+ };
+ await route.fulfill({ response, json: newJson });
+ });
+};
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('Clerk Protect checks @generic', ({ app }) => {
+ test.describe.configure({ mode: 'parallel' });
+
+ test.afterAll(async () => {
+ await app.teardown();
+ });
+
+ test('should add loader script when protect_config.loader is set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 1.0,
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-1', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-1')).toHaveAttribute('type', 'module');
+ });
+
+ test('should not add loader script when protect_config.loader is set and rollout 0.00', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 0, // force 0% rollout, should not materialize
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-2', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-2')).toHaveCount(0);
+ });
+
+ test('should not create loader element when protect_config.loader is not set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page);
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ // Playwright locators are always objects, never undefined
+ await expect(page.locator('#test-protect-loader')).toHaveCount(0);
+ });
+});

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.channel.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "65KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },

packages/clerk-js/src/core/clerk.ts

@@ -158,6 +158,7 @@ import { createClientFromJwt } from './jwt-client';
 import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
+import { Protect } from './protect';
 import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
 import { getTaskEndpoint, navigateIfTaskExists, warnMissingPendingTaskHandlers } from './sessionTasks';
 import { State } from './state';
@@ -227,6 +228,7 @@ export class Clerk implements ClerkInterface {
  #domain: DomainOrProxyUrl['domain'];
  #proxyUrl: DomainOrProxyUrl['proxyUrl'];
  #authService?: AuthCookieService;
+ #protect?: Protect;
  #captchaHeartbeat?: CaptchaHeartbeat;
  #broadcastChannel: BroadcastChannel | null = null;
  #componentControls?: ReturnType<MountComponentRenderer> | null;
@@ -429,6 +431,7 @@ export class Clerk implements ClerkInterface {
 
  // This line is used for the piggy-backing mechanism
  BaseResource.clerk = this;
+ this.#protect = new Protect();
  }
 
  public getFapiClient = (): FapiClient => this.#fapiClient;
@@ -516,6 +519,7 @@ export class Clerk implements ClerkInterface {
  ...(telemetryEnabled && this.telemetry ? { telemetryCollector: this.telemetry } : {}),
  });
  }
+ this.#protect?.load(this.environment as Environment);
  debugLogger.info('load() complete', {}, 'clerk');
  } catch (error) {
  this.#publicEventBus.emit(clerkEvents.Status, 'error');

packages/clerk-js/src/core/protect.ts

@@ -0,0 +1,97 @@
+import { inBrowser } from '@clerk/shared/browser';
+import { logger } from '@clerk/shared/logger';
+import type { ProtectLoader } from '@clerk/shared/types';
+
+import type { Environment } from './resources';
+export class Protect {
+ #initialized: boolean = false;
+
+ load(env: Environment): void {
+ const config = env?.protectConfig;
+
+ if (!config?.loaders || !Array.isArray(config.loaders) || config.loaders.length === 0) {
+ // not enabled or no protect config available
+ return;
+ } else if (this.#initialized) {
+ // already initialized - do nothing
+ return;
+ } else if (!inBrowser()) {
+ // no document: not running browser?
+ return;
+ }
+
+ // here rather than at end to mark as initialized even if load fails.
+ this.#initialized = true;
+
+ for (const loader of config.loaders) {
+ try {
+ this.applyLoader(loader);
+ } catch (error) {
+ logger.warnOnce(`[protect] failed to apply loader: ${error}`);
+ }
+ }
+ }
+
+ // apply individual loader
+ applyLoader(loader: ProtectLoader) {
+ // we use rollout for percentage based rollouts (as the environment file is cached)
+ if (loader.rollout !== undefined) {
+ const rollout = loader.rollout;
+ if (typeof rollout !== 'number' || rollout < 0) {
+ // invalid rollout percentage - do nothing
+ logger.warnOnce(`[protect] loader rollout value is invalid: ${rollout}`);
+ return;
+ }
+ if (rollout === 0 || Math.random() > rollout) {
+ // not in rollout percentage - do nothing
+ return;
+ }
+ }
+
+ const type = loader.type || 'script';
+ const target = loader.target || 'body';
+
+ const element = document.createElement(type);
+
+ if (loader.attributes) {
+ for (const [key, value] of Object.entries(loader.attributes)) {
+ switch (typeof value) {
+ case 'string':
+ case 'number':
+ case 'boolean':
+ element.setAttribute(key, String(value));
+ break;
+ default:
+ // illegal to set.
+ logger.warnOnce(`[protect] loader attribute is invalid type: ${key}=${value}`);
+ break;
+ }
+ }
+ }
+
+ if (loader.textContent && typeof loader.textContent === 'string') {
+ element.textContent = loader.textContent;
+ }
+
+ switch (target) {
+ case 'head':
+ document.head.appendChild(element);
+ break;
+ case 'body':
+ document.body.appendChild(element);
+ break;
+ default:
+ if (target?.startsWith('#')) {
+ const targetElement = document.getElementById(target.substring(1));
+ if (!targetElement) {
+ logger.warnOnce(`[protect] loader target element not found: ${target}`);
+ return;
+ }
+ targetElement.appendChild(element);
+ return;
+ }
+ logger.warnOnce(`[protect] loader target is invalid: ${target}`);
+ break;
+ }
+ }
+}

packages/clerk-js/src/core/resources/Environment.ts

@@ -6,12 +6,13 @@ import type {
  EnvironmentJSONSnapshot,
  EnvironmentResource,
  OrganizationSettingsResource,
+ ProtectConfigResource,
  UserSettingsResource,
 } from '@clerk/shared/types';
 
 import { eventBus, events } from '../../core/events';
 import { APIKeySettings } from './APIKeySettings';
-import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, UserSettings } from './internal';
+import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, ProtectConfig, UserSettings } from './internal';
 import { OrganizationSettings } from './OrganizationSettings';
 
 export class Environment extends BaseResource implements EnvironmentResource {
@@ -26,6 +27,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  organizationSettings: OrganizationSettingsResource = new OrganizationSettings();
  commerceSettings: CommerceSettingsResource = new CommerceSettings();
  apiKeysSettings: APIKeySettings = new APIKeySettings();
+ protectConfig: ProtectConfigResource = new ProtectConfig();
 
  public static getInstance(): Environment {
  if (!Environment.instance) {
@@ -54,6 +56,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  this.userSettings = new UserSettings(data.user_settings);
  this.commerceSettings = new CommerceSettings(data.commerce_settings);
  this.apiKeysSettings = new APIKeySettings(data.api_keys_settings);
+ this.protectConfig = new ProtectConfig(data.protect_config);
 
  return this;
  }
@@ -95,6 +98,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  user_settings: this.userSettings.__internal_toSnapshot(),
  commerce_settings: this.commerceSettings.__internal_toSnapshot(),
  api_keys_settings: this.apiKeysSettings.__internal_toSnapshot(),
+ protect_config: this.protectConfig.__internal_toSnapshot(),
  };
  }
 }

packages/clerk-js/src/core/resources/ProtectConfig.ts

@@ -0,0 +1,39 @@
+import type {
+ ProtectConfigJSON,
+ ProtectConfigJSONSnapshot,
+ ProtectConfigResource,
+ ProtectLoader,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class ProtectConfig extends BaseResource implements ProtectConfigResource {
+ id: string = '';
+ loaders?: ProtectLoader[];
+ rollout?: number;
+
+ public constructor(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null = null) {
+ super();
+
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = this.withDefault(data.id, this.id);
+ this.loaders = this.withDefault(data.loaders, this.loaders);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): ProtectConfigJSONSnapshot {
+ return {
+ object: 'protect_config',
+ id: this.id,
+ loaders: this.loaders,
+ };
+ }
+}

packages/clerk-js/src/core/resources/internal.ts

@@ -29,6 +29,7 @@ export * from './OrganizationSuggestion';
 export * from './SamlAccount';
 export * from './Session';
 export * from './Passkey';
+export * from './ProtectConfig';
 export * from './PublicUserData';
 export * from './SessionWithActivities';
 export * from './SignIn';

packages/shared/src/types/environment.ts

@@ -3,6 +3,7 @@ import type { AuthConfigResource } from './authConfig';
 import type { CommerceSettingsResource } from './commerceSettings';
 import type { DisplayConfigResource } from './displayConfig';
 import type { OrganizationSettingsResource } from './organizationSettings';
+import type { ProtectConfigResource } from './protectConfig';
 import type { ClerkResource } from './resource';
 import type { EnvironmentJSONSnapshot } from './snapshots';
 import type { UserSettingsResource } from './userSettings';
@@ -14,6 +15,7 @@ export interface EnvironmentResource extends ClerkResource {
  displayConfig: DisplayConfigResource;
  commerceSettings: CommerceSettingsResource;
  apiKeysSettings: APIKeysSettingsResource;
+ protectConfig: ProtectConfigResource;
  isSingleSession: () => boolean;
  isProduction: () => boolean;
  isDevelopmentOrStaging: () => boolean;

packages/shared/src/types/index.ts

@@ -46,6 +46,7 @@ export type * from './permission';
 export type * from './phoneCodeChannel';
 export type * from './phoneNumber';
 export type * from './protect';
+export type * from './protectConfig';
 export type * from './redirects';
 export type * from './resource';
 export type * from './role';

packages/shared/src/types/json.ts

@@ -25,6 +25,7 @@ import type { OrganizationCustomRoleKey, OrganizationPermissionKey } from './org
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { OrganizationSuggestionStatus } from './organizationSuggestion';
 import type { PhoneCodeChannel } from './phoneCodeChannel';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SamlIdpSlug } from './saml';
 import type { SessionStatus, SessionTask } from './session';
 import type { SessionVerificationLevel, SessionVerificationStatus } from './sessionVerification';
@@ -90,6 +91,7 @@ export interface EnvironmentJSON extends ClerkResourceJSON {
  maintenance_mode: boolean;
  organization_settings: OrganizationSettingsJSON;
  user_settings: UserSettingsJSON;
+ protect_config: ProtectConfigJSON;
 }
 
 export type LastAuthenticationStrategy =

packages/shared/src/types/protectConfig.ts

@@ -0,0 +1,22 @@
+import type { ClerkResource } from './resource';
+import type { ProtectConfigJSONSnapshot } from './snapshots';
+
+export interface ProtectLoader {
+ rollout?: number;
+ target: 'head' | 'body' | `#${string}`;
+ type: string;
+ attributes?: Record<string, string | number | boolean>;
+ textContent?: string;
+}
+
+export interface ProtectConfigJSON {
+ object: 'protect_config';
+ id: string;
+ loaders?: ProtectLoader[];
+}
+
+export interface ProtectConfigResource extends ClerkResource {
+ id: string;
+ loaders?: ProtectLoader[];
+ __internal_toSnapshot: () => ProtectConfigJSONSnapshot;
+}

packages/shared/src/types/snapshots.ts

@@ -31,6 +31,7 @@ import type {
  Web3WalletJSON,
 } from './json';
 import type { OrganizationSettingsJSON } from './organizationSettings';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SignInJSON } from './signIn';
 import type { UserSettingsJSON } from './userSettings';
 import type { Nullable, Override } from './utils';
@@ -119,6 +120,8 @@ export type EnvironmentJSONSnapshot = EnvironmentJSON;
 
 export type DisplayConfigJSONSnapshot = DisplayConfigJSON;
 
+export type ProtectConfigJSONSnapshot = ProtectConfigJSON;
+
 export type EmailAddressJSONSnapshot = Override<
  EmailAddressJSON,
  {

.changeset/beige-sloths-provide.md

@@ -0,0 +1,6 @@
+---
+"@clerk/clerk-js": minor
+"@clerk/shared": minor
+---
+
+Introduce ProtectConfig resource and Protect loader integration.

integration/tests/protect-service.test.ts

@@ -0,0 +1,76 @@
+import type { ProtectConfigJSON } from '@clerk/shared/types';
+import type { Page } from '@playwright/test';
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../presets';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+const mockProtectSettings = async (page: Page, config?: ProtectConfigJSON) => {
+ await page.route('*/**/v1/environment*', async route => {
+ const response = await route.fetch();
+ const json = await response.json();
+ const newJson = {
+ ...json,
+ ...(config ? { protect_config: config } : {}),
+ };
+ await route.fulfill({ response, json: newJson });
+ });
+};
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('Clerk Protect checks @generic', ({ app }) => {
+ test.describe.configure({ mode: 'parallel' });
+
+ test.afterAll(async () => {
+ await app.teardown();
+ });
+
+ test('should add loader script when protect_config.loader is set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 1.0,
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-1', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-1')).toHaveAttribute('type', 'module');
+ });
+
+ test('should not add loader script when protect_config.loader is set and rollout 0.00', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 0, // force 0% rollout, should not materialize
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-2', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-2')).toHaveCount(0);
+ });
+
+ test('should not create loader element when protect_config.loader is not set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page);
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ // Playwright locators are always objects, never undefined
+ await expect(page.locator('#test-protect-loader')).toHaveCount(0);
+ });
+});

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.channel.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "65KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },

packages/clerk-js/src/core/clerk.ts

@@ -158,6 +158,7 @@ import { createClientFromJwt } from './jwt-client';
 import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
+import { Protect } from './protect';
 import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
 import { getTaskEndpoint, navigateIfTaskExists, warnMissingPendingTaskHandlers } from './sessionTasks';
 import { State } from './state';
@@ -227,6 +228,7 @@ export class Clerk implements ClerkInterface {
  #domain: DomainOrProxyUrl['domain'];
  #proxyUrl: DomainOrProxyUrl['proxyUrl'];
  #authService?: AuthCookieService;
+ #protect?: Protect;
  #captchaHeartbeat?: CaptchaHeartbeat;
  #broadcastChannel: BroadcastChannel | null = null;
  #componentControls?: ReturnType<MountComponentRenderer> | null;
@@ -429,6 +431,7 @@ export class Clerk implements ClerkInterface {
 
  // This line is used for the piggy-backing mechanism
  BaseResource.clerk = this;
+ this.#protect = new Protect();
  }
 
  public getFapiClient = (): FapiClient => this.#fapiClient;
@@ -516,6 +519,7 @@ export class Clerk implements ClerkInterface {
  ...(telemetryEnabled && this.telemetry ? { telemetryCollector: this.telemetry } : {}),
  });
  }
+ this.#protect?.load(this.environment as Environment);
  debugLogger.info('load() complete', {}, 'clerk');
  } catch (error) {
  this.#publicEventBus.emit(clerkEvents.Status, 'error');

packages/clerk-js/src/core/protect.ts

@@ -0,0 +1,97 @@
+import { inBrowser } from '@clerk/shared/browser';
+import { logger } from '@clerk/shared/logger';
+import type { ProtectLoader } from '@clerk/shared/types';
+
+import type { Environment } from './resources';
+export class Protect {
+ #initialized: boolean = false;
+
+ load(env: Environment): void {
+ const config = env?.protectConfig;
+
+ if (!config?.loaders || !Array.isArray(config.loaders) || config.loaders.length === 0) {
+ // not enabled or no protect config available
+ return;
+ } else if (this.#initialized) {
+ // already initialized - do nothing
+ return;
+ } else if (!inBrowser()) {
+ // no document: not running browser?
+ return;
+ }
+
+ // here rather than at end to mark as initialized even if load fails.
+ this.#initialized = true;
+
+ for (const loader of config.loaders) {
+ try {
+ this.applyLoader(loader);
+ } catch (error) {
+ logger.warnOnce(`[protect] failed to apply loader: ${error}`);
+ }
+ }
+ }
+
+ // apply individual loader
+ applyLoader(loader: ProtectLoader) {
+ // we use rollout for percentage based rollouts (as the environment file is cached)
+ if (loader.rollout !== undefined) {
+ const rollout = loader.rollout;
+ if (typeof rollout !== 'number' || rollout < 0) {
+ // invalid rollout percentage - do nothing
+ logger.warnOnce(`[protect] loader rollout value is invalid: ${rollout}`);
+ return;
+ }
+ if (rollout === 0 || Math.random() > rollout) {
+ // not in rollout percentage - do nothing
+ return;
+ }
+ }
+
+ const type = loader.type || 'script';
+ const target = loader.target || 'body';
+
+ const element = document.createElement(type);
+
+ if (loader.attributes) {
+ for (const [key, value] of Object.entries(loader.attributes)) {
+ switch (typeof value) {
+ case 'string':
+ case 'number':
+ case 'boolean':
+ element.setAttribute(key, String(value));
+ break;
+ default:
+ // illegal to set.
+ logger.warnOnce(`[protect] loader attribute is invalid type: ${key}=${value}`);
+ break;
+ }
+ }
+ }
+
+ if (loader.textContent && typeof loader.textContent === 'string') {
+ element.textContent = loader.textContent;
+ }
+
+ switch (target) {
+ case 'head':
+ document.head.appendChild(element);
+ break;
+ case 'body':
+ document.body.appendChild(element);
+ break;
+ default:
+ if (target?.startsWith('#')) {
+ const targetElement = document.getElementById(target.substring(1));
+ if (!targetElement) {
+ logger.warnOnce(`[protect] loader target element not found: ${target}`);
+ return;
+ }
+ targetElement.appendChild(element);
+ return;
+ }
+ logger.warnOnce(`[protect] loader target is invalid: ${target}`);
+ break;
+ }
+ }
+}

packages/clerk-js/src/core/resources/Environment.ts

@@ -6,12 +6,13 @@ import type {
  EnvironmentJSONSnapshot,
  EnvironmentResource,
  OrganizationSettingsResource,
+ ProtectConfigResource,
  UserSettingsResource,
 } from '@clerk/shared/types';
 
 import { eventBus, events } from '../../core/events';
 import { APIKeySettings } from './APIKeySettings';
-import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, UserSettings } from './internal';
+import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, ProtectConfig, UserSettings } from './internal';
 import { OrganizationSettings } from './OrganizationSettings';
 
 export class Environment extends BaseResource implements EnvironmentResource {
@@ -26,6 +27,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  organizationSettings: OrganizationSettingsResource = new OrganizationSettings();
  commerceSettings: CommerceSettingsResource = new CommerceSettings();
  apiKeysSettings: APIKeySettings = new APIKeySettings();
+ protectConfig: ProtectConfigResource = new ProtectConfig();
 
  public static getInstance(): Environment {
  if (!Environment.instance) {
@@ -54,6 +56,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  this.userSettings = new UserSettings(data.user_settings);
  this.commerceSettings = new CommerceSettings(data.commerce_settings);
  this.apiKeysSettings = new APIKeySettings(data.api_keys_settings);
+ this.protectConfig = new ProtectConfig(data.protect_config);
 
  return this;
  }
@@ -95,6 +98,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  user_settings: this.userSettings.__internal_toSnapshot(),
  commerce_settings: this.commerceSettings.__internal_toSnapshot(),
  api_keys_settings: this.apiKeysSettings.__internal_toSnapshot(),
+ protect_config: this.protectConfig.__internal_toSnapshot(),
  };
  }
 }

packages/clerk-js/src/core/resources/ProtectConfig.ts

@@ -0,0 +1,39 @@
+import type {
+ ProtectConfigJSON,
+ ProtectConfigJSONSnapshot,
+ ProtectConfigResource,
+ ProtectLoader,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class ProtectConfig extends BaseResource implements ProtectConfigResource {
+ id: string = '';
+ loaders?: ProtectLoader[];
+ rollout?: number;
+
+ public constructor(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null = null) {
+ super();
+
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = this.withDefault(data.id, this.id);
+ this.loaders = this.withDefault(data.loaders, this.loaders);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): ProtectConfigJSONSnapshot {
+ return {
+ object: 'protect_config',
+ id: this.id,
+ loaders: this.loaders,
+ };
+ }
+}

packages/clerk-js/src/core/resources/internal.ts

@@ -29,6 +29,7 @@ export * from './OrganizationSuggestion';
 export * from './SamlAccount';
 export * from './Session';
 export * from './Passkey';
+export * from './ProtectConfig';
 export * from './PublicUserData';
 export * from './SessionWithActivities';
 export * from './SignIn';

packages/shared/src/types/environment.ts

@@ -3,6 +3,7 @@ import type { AuthConfigResource } from './authConfig';
 import type { CommerceSettingsResource } from './commerceSettings';
 import type { DisplayConfigResource } from './displayConfig';
 import type { OrganizationSettingsResource } from './organizationSettings';
+import type { ProtectConfigResource } from './protectConfig';
 import type { ClerkResource } from './resource';
 import type { EnvironmentJSONSnapshot } from './snapshots';
 import type { UserSettingsResource } from './userSettings';
@@ -14,6 +15,7 @@ export interface EnvironmentResource extends ClerkResource {
  displayConfig: DisplayConfigResource;
  commerceSettings: CommerceSettingsResource;
  apiKeysSettings: APIKeysSettingsResource;
+ protectConfig: ProtectConfigResource;
  isSingleSession: () => boolean;
  isProduction: () => boolean;
  isDevelopmentOrStaging: () => boolean;

packages/shared/src/types/index.ts

@@ -46,6 +46,7 @@ export type * from './permission';
 export type * from './phoneCodeChannel';
 export type * from './phoneNumber';
 export type * from './protect';
+export type * from './protectConfig';
 export type * from './redirects';
 export type * from './resource';
 export type * from './role';

packages/shared/src/types/json.ts

@@ -25,6 +25,7 @@ import type { OrganizationCustomRoleKey, OrganizationPermissionKey } from './org
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { OrganizationSuggestionStatus } from './organizationSuggestion';
 import type { PhoneCodeChannel } from './phoneCodeChannel';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SamlIdpSlug } from './saml';
 import type { SessionStatus, SessionTask } from './session';
 import type { SessionVerificationLevel, SessionVerificationStatus } from './sessionVerification';
@@ -90,6 +91,7 @@ export interface EnvironmentJSON extends ClerkResourceJSON {
  maintenance_mode: boolean;
  organization_settings: OrganizationSettingsJSON;
  user_settings: UserSettingsJSON;
+ protect_config: ProtectConfigJSON;
 }
 
 export type LastAuthenticationStrategy =

packages/shared/src/types/protectConfig.ts

@@ -0,0 +1,22 @@
+import type { ClerkResource } from './resource';
+import type { ProtectConfigJSONSnapshot } from './snapshots';
+
+export interface ProtectLoader {
+ rollout?: number;
+ target: 'head' | 'body' | `#${string}`;
+ type: string;
+ attributes?: Record<string, string | number | boolean>;
+ textContent?: string;
+}
+
+export interface ProtectConfigJSON {
+ object: 'protect_config';
+ id: string;
+ loaders?: ProtectLoader[];
+}
+
+export interface ProtectConfigResource extends ClerkResource {
+ id: string;
+ loaders?: ProtectLoader[];
+ __internal_toSnapshot: () => ProtectConfigJSONSnapshot;
+}

packages/shared/src/types/snapshots.ts

@@ -31,6 +31,7 @@ import type {
  Web3WalletJSON,
 } from './json';
 import type { OrganizationSettingsJSON } from './organizationSettings';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SignInJSON } from './signIn';
 import type { UserSettingsJSON } from './userSettings';
 import type { Nullable, Override } from './utils';
@@ -119,6 +120,8 @@ export type EnvironmentJSONSnapshot = EnvironmentJSON;
 
 export type DisplayConfigJSONSnapshot = DisplayConfigJSON;
 
+export type ProtectConfigJSONSnapshot = ProtectConfigJSON;
+
 export type EmailAddressJSONSnapshot = Override<
  EmailAddressJSON,
  {

.changeset/beige-sloths-provide.md

@@ -0,0 +1,6 @@
+---
+"@clerk/clerk-js": minor
+"@clerk/shared": minor
+---
+
+Introduce ProtectConfig resource and Protect loader integration.

integration/tests/protect-service.test.ts

@@ -0,0 +1,76 @@
+import type { ProtectConfigJSON } from '@clerk/shared/types';
+import type { Page } from '@playwright/test';
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../presets';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+const mockProtectSettings = async (page: Page, config?: ProtectConfigJSON) => {
+ await page.route('*/**/v1/environment*', async route => {
+ const response = await route.fetch();
+ const json = await response.json();
+ const newJson = {
+ ...json,
+ ...(config ? { protect_config: config } : {}),
+ };
+ await route.fulfill({ response, json: newJson });
+ });
+};
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('Clerk Protect checks @generic', ({ app }) => {
+ test.describe.configure({ mode: 'parallel' });
+
+ test.afterAll(async () => {
+ await app.teardown();
+ });
+
+ test('should add loader script when protect_config.loader is set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 1.0,
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-1', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-1')).toHaveAttribute('type', 'module');
+ });
+
+ test('should not add loader script when protect_config.loader is set and rollout 0.00', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page, {
+ object: 'protect_config',
+ id: 'n',
+ loaders: [
+ {
+ rollout: 0, // force 0% rollout, should not materialize
+ type: 'script',
+ target: 'body',
+ attributes: { id: 'test-protect-loader-2', type: 'module', src: 'data:application/json;base64,Cgo=' },
+ },
+ ],
+ });
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ await expect(page.locator('#test-protect-loader-2')).toHaveCount(0);
+ });
+
+ test('should not create loader element when protect_config.loader is not set', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await mockProtectSettings(page);
+ await u.page.goToAppHome();
+ await u.page.waitForClerkJsLoaded();
+
+ // Playwright locators are always objects, never undefined
+ await expect(page.locator('#test-protect-loader')).toHaveCount(0);
+ });
+});

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
  { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.channel.browser.js", "maxSize": "81KB" },
  { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
- { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
+ { "path": "./dist/clerk.headless*.js", "maxSize": "65KB" },
  { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
  { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
  { "path": "./dist/vendors*.js", "maxSize": "47KB" },

packages/clerk-js/src/core/clerk.ts

@@ -158,6 +158,7 @@ import { createClientFromJwt } from './jwt-client';
 import { APIKeys } from './modules/apiKeys';
 import { Billing } from './modules/billing';
 import { createCheckoutInstance } from './modules/checkout/instance';
+import { Protect } from './protect';
 import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
 import { getTaskEndpoint, navigateIfTaskExists, warnMissingPendingTaskHandlers } from './sessionTasks';
 import { State } from './state';
@@ -227,6 +228,7 @@ export class Clerk implements ClerkInterface {
  #domain: DomainOrProxyUrl['domain'];
  #proxyUrl: DomainOrProxyUrl['proxyUrl'];
  #authService?: AuthCookieService;
+ #protect?: Protect;
  #captchaHeartbeat?: CaptchaHeartbeat;
  #broadcastChannel: BroadcastChannel | null = null;
  #componentControls?: ReturnType<MountComponentRenderer> | null;
@@ -429,6 +431,7 @@ export class Clerk implements ClerkInterface {
 
  // This line is used for the piggy-backing mechanism
  BaseResource.clerk = this;
+ this.#protect = new Protect();
  }
 
  public getFapiClient = (): FapiClient => this.#fapiClient;
@@ -516,6 +519,7 @@ export class Clerk implements ClerkInterface {
  ...(telemetryEnabled && this.telemetry ? { telemetryCollector: this.telemetry } : {}),
  });
  }
+ this.#protect?.load(this.environment as Environment);
  debugLogger.info('load() complete', {}, 'clerk');
  } catch (error) {
  this.#publicEventBus.emit(clerkEvents.Status, 'error');

packages/clerk-js/src/core/protect.ts

@@ -0,0 +1,97 @@
+import { inBrowser } from '@clerk/shared/browser';
+import { logger } from '@clerk/shared/logger';
+import type { ProtectLoader } from '@clerk/shared/types';
+
+import type { Environment } from './resources';
+export class Protect {
+ #initialized: boolean = false;
+
+ load(env: Environment): void {
+ const config = env?.protectConfig;
+
+ if (!config?.loaders || !Array.isArray(config.loaders) || config.loaders.length === 0) {
+ // not enabled or no protect config available
+ return;
+ } else if (this.#initialized) {
+ // already initialized - do nothing
+ return;
+ } else if (!inBrowser()) {
+ // no document: not running browser?
+ return;
+ }
+
+ // here rather than at end to mark as initialized even if load fails.
+ this.#initialized = true;
+
+ for (const loader of config.loaders) {
+ try {
+ this.applyLoader(loader);
+ } catch (error) {
+ logger.warnOnce(`[protect] failed to apply loader: ${error}`);
+ }
+ }
+ }
+
+ // apply individual loader
+ applyLoader(loader: ProtectLoader) {
+ // we use rollout for percentage based rollouts (as the environment file is cached)
+ if (loader.rollout !== undefined) {
+ const rollout = loader.rollout;
+ if (typeof rollout !== 'number' || rollout < 0) {
+ // invalid rollout percentage - do nothing
+ logger.warnOnce(`[protect] loader rollout value is invalid: ${rollout}`);
+ return;
+ }
+ if (rollout === 0 || Math.random() > rollout) {
+ // not in rollout percentage - do nothing
+ return;
+ }
+ }
+
+ const type = loader.type || 'script';
+ const target = loader.target || 'body';
+
+ const element = document.createElement(type);
+
+ if (loader.attributes) {
+ for (const [key, value] of Object.entries(loader.attributes)) {
+ switch (typeof value) {
+ case 'string':
+ case 'number':
+ case 'boolean':
+ element.setAttribute(key, String(value));
+ break;
+ default:
+ // illegal to set.
+ logger.warnOnce(`[protect] loader attribute is invalid type: ${key}=${value}`);
+ break;
+ }
+ }
+ }
+
+ if (loader.textContent && typeof loader.textContent === 'string') {
+ element.textContent = loader.textContent;
+ }
+
+ switch (target) {
+ case 'head':
+ document.head.appendChild(element);
+ break;
+ case 'body':
+ document.body.appendChild(element);
+ break;
+ default:
+ if (target?.startsWith('#')) {
+ const targetElement = document.getElementById(target.substring(1));
+ if (!targetElement) {
+ logger.warnOnce(`[protect] loader target element not found: ${target}`);
+ return;
+ }
+ targetElement.appendChild(element);
+ return;
+ }
+ logger.warnOnce(`[protect] loader target is invalid: ${target}`);
+ break;
+ }
+ }
+}

packages/clerk-js/src/core/resources/Environment.ts

@@ -6,12 +6,13 @@ import type {
  EnvironmentJSONSnapshot,
  EnvironmentResource,
  OrganizationSettingsResource,
+ ProtectConfigResource,
  UserSettingsResource,
 } from '@clerk/shared/types';
 
 import { eventBus, events } from '../../core/events';
 import { APIKeySettings } from './APIKeySettings';
-import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, UserSettings } from './internal';
+import { AuthConfig, BaseResource, CommerceSettings, DisplayConfig, ProtectConfig, UserSettings } from './internal';
 import { OrganizationSettings } from './OrganizationSettings';
 
 export class Environment extends BaseResource implements EnvironmentResource {
@@ -26,6 +27,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  organizationSettings: OrganizationSettingsResource = new OrganizationSettings();
  commerceSettings: CommerceSettingsResource = new CommerceSettings();
  apiKeysSettings: APIKeySettings = new APIKeySettings();
+ protectConfig: ProtectConfigResource = new ProtectConfig();
 
  public static getInstance(): Environment {
  if (!Environment.instance) {
@@ -54,6 +56,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  this.userSettings = new UserSettings(data.user_settings);
  this.commerceSettings = new CommerceSettings(data.commerce_settings);
  this.apiKeysSettings = new APIKeySettings(data.api_keys_settings);
+ this.protectConfig = new ProtectConfig(data.protect_config);
 
  return this;
  }
@@ -95,6 +98,7 @@ export class Environment extends BaseResource implements EnvironmentResource {
  user_settings: this.userSettings.__internal_toSnapshot(),
  commerce_settings: this.commerceSettings.__internal_toSnapshot(),
  api_keys_settings: this.apiKeysSettings.__internal_toSnapshot(),
+ protect_config: this.protectConfig.__internal_toSnapshot(),
  };
  }
 }

packages/clerk-js/src/core/resources/ProtectConfig.ts

@@ -0,0 +1,39 @@
+import type {
+ ProtectConfigJSON,
+ ProtectConfigJSONSnapshot,
+ ProtectConfigResource,
+ ProtectLoader,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class ProtectConfig extends BaseResource implements ProtectConfigResource {
+ id: string = '';
+ loaders?: ProtectLoader[];
+ rollout?: number;
+
+ public constructor(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null = null) {
+ super();
+
+ this.fromJSON(data);
+ }
+
+ protected fromJSON(data: ProtectConfigJSON | ProtectConfigJSONSnapshot | null): this {
+ if (!data) {
+ return this;
+ }
+
+ this.id = this.withDefault(data.id, this.id);
+ this.loaders = this.withDefault(data.loaders, this.loaders);
+
+ return this;
+ }
+
+ public __internal_toSnapshot(): ProtectConfigJSONSnapshot {
+ return {
+ object: 'protect_config',
+ id: this.id,
+ loaders: this.loaders,
+ };
+ }
+}

packages/clerk-js/src/core/resources/internal.ts

@@ -29,6 +29,7 @@ export * from './OrganizationSuggestion';
 export * from './SamlAccount';
 export * from './Session';
 export * from './Passkey';
+export * from './ProtectConfig';
 export * from './PublicUserData';
 export * from './SessionWithActivities';
 export * from './SignIn';

packages/shared/src/types/environment.ts

@@ -3,6 +3,7 @@ import type { AuthConfigResource } from './authConfig';
 import type { CommerceSettingsResource } from './commerceSettings';
 import type { DisplayConfigResource } from './displayConfig';
 import type { OrganizationSettingsResource } from './organizationSettings';
+import type { ProtectConfigResource } from './protectConfig';
 import type { ClerkResource } from './resource';
 import type { EnvironmentJSONSnapshot } from './snapshots';
 import type { UserSettingsResource } from './userSettings';
@@ -14,6 +15,7 @@ export interface EnvironmentResource extends ClerkResource {
  displayConfig: DisplayConfigResource;
  commerceSettings: CommerceSettingsResource;
  apiKeysSettings: APIKeysSettingsResource;
+ protectConfig: ProtectConfigResource;
  isSingleSession: () => boolean;
  isProduction: () => boolean;
  isDevelopmentOrStaging: () => boolean;

packages/shared/src/types/index.ts

@@ -46,6 +46,7 @@ export type * from './permission';
 export type * from './phoneCodeChannel';
 export type * from './phoneNumber';
 export type * from './protect';
+export type * from './protectConfig';
 export type * from './redirects';
 export type * from './resource';
 export type * from './role';

packages/shared/src/types/json.ts

@@ -25,6 +25,7 @@ import type { OrganizationCustomRoleKey, OrganizationPermissionKey } from './org
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { OrganizationSuggestionStatus } from './organizationSuggestion';
 import type { PhoneCodeChannel } from './phoneCodeChannel';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SamlIdpSlug } from './saml';
 import type { SessionStatus, SessionTask } from './session';
 import type { SessionVerificationLevel, SessionVerificationStatus } from './sessionVerification';
@@ -90,6 +91,7 @@ export interface EnvironmentJSON extends ClerkResourceJSON {
  maintenance_mode: boolean;
  organization_settings: OrganizationSettingsJSON;
  user_settings: UserSettingsJSON;
+ protect_config: ProtectConfigJSON;
 }
 
 export type LastAuthenticationStrategy =

packages/shared/src/types/protectConfig.ts

@@ -0,0 +1,22 @@
+import type { ClerkResource } from './resource';
+import type { ProtectConfigJSONSnapshot } from './snapshots';
+
+export interface ProtectLoader {
+ rollout?: number;
+ target: 'head' | 'body' | `#${string}`;
+ type: string;
+ attributes?: Record<string, string | number | boolean>;
+ textContent?: string;
+}
+
+export interface ProtectConfigJSON {
+ object: 'protect_config';
+ id: string;
+ loaders?: ProtectLoader[];
+}
+
+export interface ProtectConfigResource extends ClerkResource {
+ id: string;
+ loaders?: ProtectLoader[];
+ __internal_toSnapshot: () => ProtectConfigJSONSnapshot;
+}

packages/shared/src/types/snapshots.ts

@@ -31,6 +31,7 @@ import type {
  Web3WalletJSON,
 } from './json';
 import type { OrganizationSettingsJSON } from './organizationSettings';
+import type { ProtectConfigJSON } from './protectConfig';
 import type { SignInJSON } from './signIn';
 import type { UserSettingsJSON } from './userSettings';
 import type { Nullable, Override } from './utils';
@@ -119,6 +120,8 @@ export type EnvironmentJSONSnapshot = EnvironmentJSON;
 
 export type DisplayConfigJSONSnapshot = DisplayConfigJSON;
 
+export type ProtectConfigJSONSnapshot = ProtectConfigJSON;
+
 export type EmailAddressJSONSnapshot = Override<
  EmailAddressJSON,
  {