fix(repo): harden keyless accountless requests

.changeset/keyless-ci-guard.md

@@ -0,0 +1,11 @@
+---
+'@clerk/astro': patch
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+'@clerk/nuxt': patch
+'@clerk/react-router': patch
+'@clerk/shared': patch
+'@clerk/tanstack-react-start': patch
+---
+
+Prevent keyless mode from activating in CI and other automated environments in framework SDKs.

integration/models/__tests__/application.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { resolveServerUrl } from '../application';
+import { createAppRuntimeEnv, resolveServerUrl } from '../application';
+import { environmentConfig } from '../environment';
 
 describe('resolveServerUrl', () => {
  describe('with opts.serverUrl', () => {
@@ -49,3 +50,16 @@ describe('resolveServerUrl', () => {
  });
  });
 });
+
+describe('createAppRuntimeEnv', () => {
+ it('passes configured falsey values through to spawned app processes', () => {
+ const env = environmentConfig()
+ .setEnvVariable('private', 'CI', 'false')
+ .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
+
+ expect(createAppRuntimeEnv(env)).toMatchObject({
+ CI: 'false',
+ CLERK_KEYLESS_DISABLED: 'false',
+ });
+ });
+});

integration/models/application.ts

@@ -34,6 +34,24 @@ export const resolveServerUrl = (
  return fallbackServerUrl || `http://localhost:${port}`;
 };
 
+export const createAppRuntimeEnv = (env?: EnvironmentConfig): Record<string, string> => {
+ if (!env?.publicVariables || !env?.privateVariables) {
+ return {};
+ }
+
+ const runtimeEnv: Record<string, string> = {};
+ // Private variables intentionally win when the same runtime key exists in both maps.
+ for (const [key, value] of [...env.publicVariables, ...env.privateVariables]) {
+ if (value === undefined || value === null) {
+ continue;
+ }
+
+ runtimeEnv[key] = String(value);
+ }
+
+ return runtimeEnv;
+};
+
 export const application = (
  config: ApplicationConfig,
  appDirPath: string,
@@ -103,7 +121,7 @@ export const application = (
 
  const proc = run(scripts.dev, {
  cwd: appDirPath,
- env: { PORT: port.toString() },
+ env: { ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,
@@ -158,6 +176,7 @@ export const application = (
  const log = logger.child({ prefix: 'build' }).info;
  await run(scripts.build, {
  cwd: appDirPath,
+ env: createAppRuntimeEnv(state.env),
  log: (msg: string) => {
  buildOutput += `\n${msg}`;
  log(msg);
@@ -200,7 +219,7 @@ export const application = (
 
  const proc = run(scripts.serve, {
  cwd: appDirPath,
- env: { ...envFromFile, PORT: port.toString() },
+ env: { ...envFromFile, ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,

integration/presets/envs.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
 import fs from 'fs-extra';
 
 import { constants } from '../constants';
@@ -91,6 +92,10 @@ const withKeyless = base
  .setEnvVariable('private', 'CLERK_API_URL', 'https://api.clerkstage.dev')
  .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
 
+automatedEnvironmentVariables.forEach(name => {
+ withKeyless.setEnvVariable('private', name, 'false');
+});
+
 const withEmailCodes = withInstanceKeys(
  'with-email-codes',
  base

packages/astro/src/server/keyless/index.ts

@@ -12,21 +12,23 @@ export function keyless(context: APIContext) {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(context).__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(
  context,
  ).__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

packages/astro/src/utils/__tests__/feature-flags.test.ts

@@ -0,0 +1,48 @@
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+async function loadCanUseKeyless() {
+ vi.resetModules();
+ const { canUseKeyless } = await import('../feature-flags.js');
+ return canUseKeyless;
+}
+
+describe('canUseKeyless', () => {
+ beforeEach(() => {
+ vi.stubEnv('NODE_ENV', 'development');
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', undefined);
+ vi.stubEnv('CLERK_KEYLESS_DISABLED', undefined);
+ automatedEnvironmentVariables.forEach(name => {
+ vi.stubEnv(name, undefined);
+ vi.stubGlobal(name, undefined);
+ });
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ vi.resetModules();
+ });
+
+ it('enables keyless in development when automation signals are absent', async () => {
+ await expect(loadCanUseKeyless()).resolves.toBe(true);
+ });
+
+ it('disables keyless in CI even when the app runs in development mode', async () => {
+ vi.stubEnv('CI', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless outside development mode', async () => {
+ vi.stubEnv('NODE_ENV', 'production');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless when explicitly disabled', async () => {
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+});

packages/astro/src/utils/feature-flags.ts

@@ -1,10 +1,10 @@
 import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { isTruthy } from '@clerk/shared/underscore';
-import { isDevelopmentEnvironment } from '@clerk/shared/utils';
+import { isAutomatedEnvironment, isDevelopmentEnvironment } from '@clerk/shared/utils';
 
 const KEYLESS_DISABLED =
  isTruthy(getEnvVariable('PUBLIC_CLERK_KEYLESS_DISABLED')) ||
  isTruthy(getEnvVariable('CLERK_KEYLESS_DISABLED')) ||
  false;
 
-export const canUseKeyless = isDevelopmentEnvironment() && !KEYLESS_DISABLED;
+export const canUseKeyless = isDevelopmentEnvironment() && !isAutomatedEnvironment() && !KEYLESS_DISABLED;

packages/backend/src/api/__tests__/AccountlessApplicationsApi.test.ts

@@ -0,0 +1,99 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('AccountlessApplications', () => {
+ const mockAccountlessApplication = {
+ object: 'accountless_application',
+ publishable_key: 'pk_test_keyless',
+ secret_key: 'sk_test_keyless',
+ claim_url: 'https://dashboard.clerk.com/claim',
+ api_keys_url: 'https://dashboard.clerk.com/api-keys',
+ };
+
+ it('creates an accountless application with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('creates an accountless application without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+});

packages/backend/src/api/endpoints/AccountlessApplicationsAPI.ts

@@ -4,22 +4,35 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/accountless_applications';
 
+type AccountlessApplicationParams = {
+ requestHeaders?: Headers;
+ source?: string;
+};
+
 export class AccountlessApplicationAPI extends AbstractAPI {
- public async createAccountlessApplication(params?: { requestHeaders?: Headers }) {
+ public async createAccountlessApplication(params?: AccountlessApplicationParams): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: basePath,
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 
- public async completeAccountlessApplicationOnboarding(params?: { requestHeaders?: Headers }) {
+ public async completeAccountlessApplicationOnboarding(
+ params?: AccountlessApplicationParams,
+ ): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: joinPaths(basePath, 'complete'),
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 }

packages/nextjs/src/server/keyless-node.ts

@@ -24,19 +24,21 @@ export function keyless() {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

.changeset/keyless-ci-guard.md

@@ -0,0 +1,11 @@
+---
+'@clerk/astro': patch
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+'@clerk/nuxt': patch
+'@clerk/react-router': patch
+'@clerk/shared': patch
+'@clerk/tanstack-react-start': patch
+---
+
+Prevent keyless mode from activating in CI and other automated environments in framework SDKs.

integration/models/__tests__/application.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { resolveServerUrl } from '../application';
+import { createAppRuntimeEnv, resolveServerUrl } from '../application';
+import { environmentConfig } from '../environment';
 
 describe('resolveServerUrl', () => {
  describe('with opts.serverUrl', () => {
@@ -49,3 +50,16 @@ describe('resolveServerUrl', () => {
  });
  });
 });
+
+describe('createAppRuntimeEnv', () => {
+ it('passes configured falsey values through to spawned app processes', () => {
+ const env = environmentConfig()
+ .setEnvVariable('private', 'CI', 'false')
+ .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
+
+ expect(createAppRuntimeEnv(env)).toMatchObject({
+ CI: 'false',
+ CLERK_KEYLESS_DISABLED: 'false',
+ });
+ });
+});

integration/models/application.ts

@@ -34,6 +34,24 @@ export const resolveServerUrl = (
  return fallbackServerUrl || `http://localhost:${port}`;
 };
 
+export const createAppRuntimeEnv = (env?: EnvironmentConfig): Record<string, string> => {
+ if (!env?.publicVariables || !env?.privateVariables) {
+ return {};
+ }
+
+ const runtimeEnv: Record<string, string> = {};
+ // Private variables intentionally win when the same runtime key exists in both maps.
+ for (const [key, value] of [...env.publicVariables, ...env.privateVariables]) {
+ if (value === undefined || value === null) {
+ continue;
+ }
+
+ runtimeEnv[key] = String(value);
+ }
+
+ return runtimeEnv;
+};
+
 export const application = (
  config: ApplicationConfig,
  appDirPath: string,
@@ -103,7 +121,7 @@ export const application = (
 
  const proc = run(scripts.dev, {
  cwd: appDirPath,
- env: { PORT: port.toString() },
+ env: { ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,
@@ -158,6 +176,7 @@ export const application = (
  const log = logger.child({ prefix: 'build' }).info;
  await run(scripts.build, {
  cwd: appDirPath,
+ env: createAppRuntimeEnv(state.env),
  log: (msg: string) => {
  buildOutput += `\n${msg}`;
  log(msg);
@@ -200,7 +219,7 @@ export const application = (
 
  const proc = run(scripts.serve, {
  cwd: appDirPath,
- env: { ...envFromFile, PORT: port.toString() },
+ env: { ...envFromFile, ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,

integration/presets/envs.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
 import fs from 'fs-extra';
 
 import { constants } from '../constants';
@@ -91,6 +92,10 @@ const withKeyless = base
  .setEnvVariable('private', 'CLERK_API_URL', 'https://api.clerkstage.dev')
  .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
 
+automatedEnvironmentVariables.forEach(name => {
+ withKeyless.setEnvVariable('private', name, 'false');
+});
+
 const withEmailCodes = withInstanceKeys(
  'with-email-codes',
  base

packages/astro/src/server/keyless/index.ts

@@ -12,21 +12,23 @@ export function keyless(context: APIContext) {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(context).__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(
  context,
  ).__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

packages/astro/src/utils/__tests__/feature-flags.test.ts

@@ -0,0 +1,48 @@
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+async function loadCanUseKeyless() {
+ vi.resetModules();
+ const { canUseKeyless } = await import('../feature-flags.js');
+ return canUseKeyless;
+}
+
+describe('canUseKeyless', () => {
+ beforeEach(() => {
+ vi.stubEnv('NODE_ENV', 'development');
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', undefined);
+ vi.stubEnv('CLERK_KEYLESS_DISABLED', undefined);
+ automatedEnvironmentVariables.forEach(name => {
+ vi.stubEnv(name, undefined);
+ vi.stubGlobal(name, undefined);
+ });
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ vi.resetModules();
+ });
+
+ it('enables keyless in development when automation signals are absent', async () => {
+ await expect(loadCanUseKeyless()).resolves.toBe(true);
+ });
+
+ it('disables keyless in CI even when the app runs in development mode', async () => {
+ vi.stubEnv('CI', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless outside development mode', async () => {
+ vi.stubEnv('NODE_ENV', 'production');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless when explicitly disabled', async () => {
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+});

packages/astro/src/utils/feature-flags.ts

@@ -1,10 +1,10 @@
 import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { isTruthy } from '@clerk/shared/underscore';
-import { isDevelopmentEnvironment } from '@clerk/shared/utils';
+import { isAutomatedEnvironment, isDevelopmentEnvironment } from '@clerk/shared/utils';
 
 const KEYLESS_DISABLED =
  isTruthy(getEnvVariable('PUBLIC_CLERK_KEYLESS_DISABLED')) ||
  isTruthy(getEnvVariable('CLERK_KEYLESS_DISABLED')) ||
  false;
 
-export const canUseKeyless = isDevelopmentEnvironment() && !KEYLESS_DISABLED;
+export const canUseKeyless = isDevelopmentEnvironment() && !isAutomatedEnvironment() && !KEYLESS_DISABLED;

packages/backend/src/api/__tests__/AccountlessApplicationsApi.test.ts

@@ -0,0 +1,99 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('AccountlessApplications', () => {
+ const mockAccountlessApplication = {
+ object: 'accountless_application',
+ publishable_key: 'pk_test_keyless',
+ secret_key: 'sk_test_keyless',
+ claim_url: 'https://dashboard.clerk.com/claim',
+ api_keys_url: 'https://dashboard.clerk.com/api-keys',
+ };
+
+ it('creates an accountless application with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('creates an accountless application without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+});

packages/backend/src/api/endpoints/AccountlessApplicationsAPI.ts

@@ -4,22 +4,35 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/accountless_applications';
 
+type AccountlessApplicationParams = {
+ requestHeaders?: Headers;
+ source?: string;
+};
+
 export class AccountlessApplicationAPI extends AbstractAPI {
- public async createAccountlessApplication(params?: { requestHeaders?: Headers }) {
+ public async createAccountlessApplication(params?: AccountlessApplicationParams): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: basePath,
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 
- public async completeAccountlessApplicationOnboarding(params?: { requestHeaders?: Headers }) {
+ public async completeAccountlessApplicationOnboarding(
+ params?: AccountlessApplicationParams,
+ ): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: joinPaths(basePath, 'complete'),
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 }

packages/nextjs/src/server/keyless-node.ts

@@ -24,19 +24,21 @@ export function keyless() {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

.changeset/keyless-ci-guard.md

@@ -0,0 +1,11 @@
+---
+'@clerk/astro': patch
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+'@clerk/nuxt': patch
+'@clerk/react-router': patch
+'@clerk/shared': patch
+'@clerk/tanstack-react-start': patch
+---
+
+Prevent keyless mode from activating in CI and other automated environments in framework SDKs.

integration/models/__tests__/application.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { resolveServerUrl } from '../application';
+import { createAppRuntimeEnv, resolveServerUrl } from '../application';
+import { environmentConfig } from '../environment';
 
 describe('resolveServerUrl', () => {
  describe('with opts.serverUrl', () => {
@@ -49,3 +50,16 @@ describe('resolveServerUrl', () => {
  });
  });
 });
+
+describe('createAppRuntimeEnv', () => {
+ it('passes configured falsey values through to spawned app processes', () => {
+ const env = environmentConfig()
+ .setEnvVariable('private', 'CI', 'false')
+ .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
+
+ expect(createAppRuntimeEnv(env)).toMatchObject({
+ CI: 'false',
+ CLERK_KEYLESS_DISABLED: 'false',
+ });
+ });
+});

integration/models/application.ts

@@ -34,6 +34,24 @@ export const resolveServerUrl = (
  return fallbackServerUrl || `http://localhost:${port}`;
 };
 
+export const createAppRuntimeEnv = (env?: EnvironmentConfig): Record<string, string> => {
+ if (!env?.publicVariables || !env?.privateVariables) {
+ return {};
+ }
+
+ const runtimeEnv: Record<string, string> = {};
+ // Private variables intentionally win when the same runtime key exists in both maps.
+ for (const [key, value] of [...env.publicVariables, ...env.privateVariables]) {
+ if (value === undefined || value === null) {
+ continue;
+ }
+
+ runtimeEnv[key] = String(value);
+ }
+
+ return runtimeEnv;
+};
+
 export const application = (
  config: ApplicationConfig,
  appDirPath: string,
@@ -103,7 +121,7 @@ export const application = (
 
  const proc = run(scripts.dev, {
  cwd: appDirPath,
- env: { PORT: port.toString() },
+ env: { ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,
@@ -158,6 +176,7 @@ export const application = (
  const log = logger.child({ prefix: 'build' }).info;
  await run(scripts.build, {
  cwd: appDirPath,
+ env: createAppRuntimeEnv(state.env),
  log: (msg: string) => {
  buildOutput += `\n${msg}`;
  log(msg);
@@ -200,7 +219,7 @@ export const application = (
 
  const proc = run(scripts.serve, {
  cwd: appDirPath,
- env: { ...envFromFile, PORT: port.toString() },
+ env: { ...envFromFile, ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,

integration/presets/envs.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
 import fs from 'fs-extra';
 
 import { constants } from '../constants';
@@ -91,6 +92,10 @@ const withKeyless = base
  .setEnvVariable('private', 'CLERK_API_URL', 'https://api.clerkstage.dev')
  .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
 
+automatedEnvironmentVariables.forEach(name => {
+ withKeyless.setEnvVariable('private', name, 'false');
+});
+
 const withEmailCodes = withInstanceKeys(
  'with-email-codes',
  base

packages/astro/src/server/keyless/index.ts

@@ -12,21 +12,23 @@ export function keyless(context: APIContext) {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(context).__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(
  context,
  ).__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

packages/astro/src/utils/__tests__/feature-flags.test.ts

@@ -0,0 +1,48 @@
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+async function loadCanUseKeyless() {
+ vi.resetModules();
+ const { canUseKeyless } = await import('../feature-flags.js');
+ return canUseKeyless;
+}
+
+describe('canUseKeyless', () => {
+ beforeEach(() => {
+ vi.stubEnv('NODE_ENV', 'development');
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', undefined);
+ vi.stubEnv('CLERK_KEYLESS_DISABLED', undefined);
+ automatedEnvironmentVariables.forEach(name => {
+ vi.stubEnv(name, undefined);
+ vi.stubGlobal(name, undefined);
+ });
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ vi.resetModules();
+ });
+
+ it('enables keyless in development when automation signals are absent', async () => {
+ await expect(loadCanUseKeyless()).resolves.toBe(true);
+ });
+
+ it('disables keyless in CI even when the app runs in development mode', async () => {
+ vi.stubEnv('CI', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless outside development mode', async () => {
+ vi.stubEnv('NODE_ENV', 'production');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless when explicitly disabled', async () => {
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+});

packages/astro/src/utils/feature-flags.ts

@@ -1,10 +1,10 @@
 import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { isTruthy } from '@clerk/shared/underscore';
-import { isDevelopmentEnvironment } from '@clerk/shared/utils';
+import { isAutomatedEnvironment, isDevelopmentEnvironment } from '@clerk/shared/utils';
 
 const KEYLESS_DISABLED =
  isTruthy(getEnvVariable('PUBLIC_CLERK_KEYLESS_DISABLED')) ||
  isTruthy(getEnvVariable('CLERK_KEYLESS_DISABLED')) ||
  false;
 
-export const canUseKeyless = isDevelopmentEnvironment() && !KEYLESS_DISABLED;
+export const canUseKeyless = isDevelopmentEnvironment() && !isAutomatedEnvironment() && !KEYLESS_DISABLED;

packages/backend/src/api/__tests__/AccountlessApplicationsApi.test.ts

@@ -0,0 +1,99 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('AccountlessApplications', () => {
+ const mockAccountlessApplication = {
+ object: 'accountless_application',
+ publishable_key: 'pk_test_keyless',
+ secret_key: 'sk_test_keyless',
+ claim_url: 'https://dashboard.clerk.com/claim',
+ api_keys_url: 'https://dashboard.clerk.com/api-keys',
+ };
+
+ it('creates an accountless application with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('creates an accountless application without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+});

packages/backend/src/api/endpoints/AccountlessApplicationsAPI.ts

@@ -4,22 +4,35 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/accountless_applications';
 
+type AccountlessApplicationParams = {
+ requestHeaders?: Headers;
+ source?: string;
+};
+
 export class AccountlessApplicationAPI extends AbstractAPI {
- public async createAccountlessApplication(params?: { requestHeaders?: Headers }) {
+ public async createAccountlessApplication(params?: AccountlessApplicationParams): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: basePath,
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 
- public async completeAccountlessApplicationOnboarding(params?: { requestHeaders?: Headers }) {
+ public async completeAccountlessApplicationOnboarding(
+ params?: AccountlessApplicationParams,
+ ): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: joinPaths(basePath, 'complete'),
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 }

packages/nextjs/src/server/keyless-node.ts

@@ -24,19 +24,21 @@ export function keyless() {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

.changeset/keyless-ci-guard.md

@@ -0,0 +1,11 @@
+---
+'@clerk/astro': patch
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+'@clerk/nuxt': patch
+'@clerk/react-router': patch
+'@clerk/shared': patch
+'@clerk/tanstack-react-start': patch
+---
+
+Prevent keyless mode from activating in CI and other automated environments in framework SDKs.

integration/models/__tests__/application.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { resolveServerUrl } from '../application';
+import { createAppRuntimeEnv, resolveServerUrl } from '../application';
+import { environmentConfig } from '../environment';
 
 describe('resolveServerUrl', () => {
  describe('with opts.serverUrl', () => {
@@ -49,3 +50,16 @@ describe('resolveServerUrl', () => {
  });
  });
 });
+
+describe('createAppRuntimeEnv', () => {
+ it('passes configured falsey values through to spawned app processes', () => {
+ const env = environmentConfig()
+ .setEnvVariable('private', 'CI', 'false')
+ .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
+
+ expect(createAppRuntimeEnv(env)).toMatchObject({
+ CI: 'false',
+ CLERK_KEYLESS_DISABLED: 'false',
+ });
+ });
+});

integration/models/application.ts

@@ -34,6 +34,24 @@ export const resolveServerUrl = (
  return fallbackServerUrl || `http://localhost:${port}`;
 };
 
+export const createAppRuntimeEnv = (env?: EnvironmentConfig): Record<string, string> => {
+ if (!env?.publicVariables || !env?.privateVariables) {
+ return {};
+ }
+
+ const runtimeEnv: Record<string, string> = {};
+ // Private variables intentionally win when the same runtime key exists in both maps.
+ for (const [key, value] of [...env.publicVariables, ...env.privateVariables]) {
+ if (value === undefined || value === null) {
+ continue;
+ }
+
+ runtimeEnv[key] = String(value);
+ }
+
+ return runtimeEnv;
+};
+
 export const application = (
  config: ApplicationConfig,
  appDirPath: string,
@@ -103,7 +121,7 @@ export const application = (
 
  const proc = run(scripts.dev, {
  cwd: appDirPath,
- env: { PORT: port.toString() },
+ env: { ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,
@@ -158,6 +176,7 @@ export const application = (
  const log = logger.child({ prefix: 'build' }).info;
  await run(scripts.build, {
  cwd: appDirPath,
+ env: createAppRuntimeEnv(state.env),
  log: (msg: string) => {
  buildOutput += `\n${msg}`;
  log(msg);
@@ -200,7 +219,7 @@ export const application = (
 
  const proc = run(scripts.serve, {
  cwd: appDirPath,
- env: { ...envFromFile, PORT: port.toString() },
+ env: { ...envFromFile, ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,

integration/presets/envs.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
 import fs from 'fs-extra';
 
 import { constants } from '../constants';
@@ -91,6 +92,10 @@ const withKeyless = base
  .setEnvVariable('private', 'CLERK_API_URL', 'https://api.clerkstage.dev')
  .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
 
+automatedEnvironmentVariables.forEach(name => {
+ withKeyless.setEnvVariable('private', name, 'false');
+});
+
 const withEmailCodes = withInstanceKeys(
  'with-email-codes',
  base

packages/astro/src/server/keyless/index.ts

@@ -12,21 +12,23 @@ export function keyless(context: APIContext) {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(context).__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(
  context,
  ).__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

packages/astro/src/utils/__tests__/feature-flags.test.ts

@@ -0,0 +1,48 @@
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+async function loadCanUseKeyless() {
+ vi.resetModules();
+ const { canUseKeyless } = await import('../feature-flags.js');
+ return canUseKeyless;
+}
+
+describe('canUseKeyless', () => {
+ beforeEach(() => {
+ vi.stubEnv('NODE_ENV', 'development');
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', undefined);
+ vi.stubEnv('CLERK_KEYLESS_DISABLED', undefined);
+ automatedEnvironmentVariables.forEach(name => {
+ vi.stubEnv(name, undefined);
+ vi.stubGlobal(name, undefined);
+ });
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ vi.resetModules();
+ });
+
+ it('enables keyless in development when automation signals are absent', async () => {
+ await expect(loadCanUseKeyless()).resolves.toBe(true);
+ });
+
+ it('disables keyless in CI even when the app runs in development mode', async () => {
+ vi.stubEnv('CI', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless outside development mode', async () => {
+ vi.stubEnv('NODE_ENV', 'production');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless when explicitly disabled', async () => {
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+});

packages/astro/src/utils/feature-flags.ts

@@ -1,10 +1,10 @@
 import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { isTruthy } from '@clerk/shared/underscore';
-import { isDevelopmentEnvironment } from '@clerk/shared/utils';
+import { isAutomatedEnvironment, isDevelopmentEnvironment } from '@clerk/shared/utils';
 
 const KEYLESS_DISABLED =
  isTruthy(getEnvVariable('PUBLIC_CLERK_KEYLESS_DISABLED')) ||
  isTruthy(getEnvVariable('CLERK_KEYLESS_DISABLED')) ||
  false;
 
-export const canUseKeyless = isDevelopmentEnvironment() && !KEYLESS_DISABLED;
+export const canUseKeyless = isDevelopmentEnvironment() && !isAutomatedEnvironment() && !KEYLESS_DISABLED;

packages/backend/src/api/__tests__/AccountlessApplicationsApi.test.ts

@@ -0,0 +1,99 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('AccountlessApplications', () => {
+ const mockAccountlessApplication = {
+ object: 'accountless_application',
+ publishable_key: 'pk_test_keyless',
+ secret_key: 'sk_test_keyless',
+ claim_url: 'https://dashboard.clerk.com/claim',
+ api_keys_url: 'https://dashboard.clerk.com/api-keys',
+ };
+
+ it('creates an accountless application with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('creates an accountless application without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+});

packages/backend/src/api/endpoints/AccountlessApplicationsAPI.ts

@@ -4,22 +4,35 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/accountless_applications';
 
+type AccountlessApplicationParams = {
+ requestHeaders?: Headers;
+ source?: string;
+};
+
 export class AccountlessApplicationAPI extends AbstractAPI {
- public async createAccountlessApplication(params?: { requestHeaders?: Headers }) {
+ public async createAccountlessApplication(params?: AccountlessApplicationParams): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: basePath,
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 
- public async completeAccountlessApplicationOnboarding(params?: { requestHeaders?: Headers }) {
+ public async completeAccountlessApplicationOnboarding(
+ params?: AccountlessApplicationParams,
+ ): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: joinPaths(basePath, 'complete'),
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 }

packages/nextjs/src/server/keyless-node.ts

@@ -24,19 +24,21 @@ export function keyless() {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

.changeset/keyless-ci-guard.md

@@ -0,0 +1,11 @@
+---
+'@clerk/astro': patch
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+'@clerk/nuxt': patch
+'@clerk/react-router': patch
+'@clerk/shared': patch
+'@clerk/tanstack-react-start': patch
+---
+
+Prevent keyless mode from activating in CI and other automated environments in framework SDKs.

integration/models/__tests__/application.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { resolveServerUrl } from '../application';
+import { createAppRuntimeEnv, resolveServerUrl } from '../application';
+import { environmentConfig } from '../environment';
 
 describe('resolveServerUrl', () => {
  describe('with opts.serverUrl', () => {
@@ -49,3 +50,16 @@ describe('resolveServerUrl', () => {
  });
  });
 });
+
+describe('createAppRuntimeEnv', () => {
+ it('passes configured falsey values through to spawned app processes', () => {
+ const env = environmentConfig()
+ .setEnvVariable('private', 'CI', 'false')
+ .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
+
+ expect(createAppRuntimeEnv(env)).toMatchObject({
+ CI: 'false',
+ CLERK_KEYLESS_DISABLED: 'false',
+ });
+ });
+});

integration/models/application.ts

@@ -34,6 +34,24 @@ export const resolveServerUrl = (
  return fallbackServerUrl || `http://localhost:${port}`;
 };
 
+export const createAppRuntimeEnv = (env?: EnvironmentConfig): Record<string, string> => {
+ if (!env?.publicVariables || !env?.privateVariables) {
+ return {};
+ }
+
+ const runtimeEnv: Record<string, string> = {};
+ // Private variables intentionally win when the same runtime key exists in both maps.
+ for (const [key, value] of [...env.publicVariables, ...env.privateVariables]) {
+ if (value === undefined || value === null) {
+ continue;
+ }
+
+ runtimeEnv[key] = String(value);
+ }
+
+ return runtimeEnv;
+};
+
 export const application = (
  config: ApplicationConfig,
  appDirPath: string,
@@ -103,7 +121,7 @@ export const application = (
 
  const proc = run(scripts.dev, {
  cwd: appDirPath,
- env: { PORT: port.toString() },
+ env: { ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,
@@ -158,6 +176,7 @@ export const application = (
  const log = logger.child({ prefix: 'build' }).info;
  await run(scripts.build, {
  cwd: appDirPath,
+ env: createAppRuntimeEnv(state.env),
  log: (msg: string) => {
  buildOutput += `\n${msg}`;
  log(msg);
@@ -200,7 +219,7 @@ export const application = (
 
  const proc = run(scripts.serve, {
  cwd: appDirPath,
- env: { ...envFromFile, PORT: port.toString() },
+ env: { ...envFromFile, ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,

integration/presets/envs.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
 import fs from 'fs-extra';
 
 import { constants } from '../constants';
@@ -91,6 +92,10 @@ const withKeyless = base
  .setEnvVariable('private', 'CLERK_API_URL', 'https://api.clerkstage.dev')
  .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
 
+automatedEnvironmentVariables.forEach(name => {
+ withKeyless.setEnvVariable('private', name, 'false');
+});
+
 const withEmailCodes = withInstanceKeys(
  'with-email-codes',
  base

packages/astro/src/server/keyless/index.ts

@@ -12,21 +12,23 @@ export function keyless(context: APIContext) {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(context).__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(
  context,
  ).__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

packages/astro/src/utils/__tests__/feature-flags.test.ts

@@ -0,0 +1,48 @@
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+async function loadCanUseKeyless() {
+ vi.resetModules();
+ const { canUseKeyless } = await import('../feature-flags.js');
+ return canUseKeyless;
+}
+
+describe('canUseKeyless', () => {
+ beforeEach(() => {
+ vi.stubEnv('NODE_ENV', 'development');
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', undefined);
+ vi.stubEnv('CLERK_KEYLESS_DISABLED', undefined);
+ automatedEnvironmentVariables.forEach(name => {
+ vi.stubEnv(name, undefined);
+ vi.stubGlobal(name, undefined);
+ });
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ vi.resetModules();
+ });
+
+ it('enables keyless in development when automation signals are absent', async () => {
+ await expect(loadCanUseKeyless()).resolves.toBe(true);
+ });
+
+ it('disables keyless in CI even when the app runs in development mode', async () => {
+ vi.stubEnv('CI', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless outside development mode', async () => {
+ vi.stubEnv('NODE_ENV', 'production');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless when explicitly disabled', async () => {
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+});

packages/astro/src/utils/feature-flags.ts

@@ -1,10 +1,10 @@
 import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { isTruthy } from '@clerk/shared/underscore';
-import { isDevelopmentEnvironment } from '@clerk/shared/utils';
+import { isAutomatedEnvironment, isDevelopmentEnvironment } from '@clerk/shared/utils';
 
 const KEYLESS_DISABLED =
  isTruthy(getEnvVariable('PUBLIC_CLERK_KEYLESS_DISABLED')) ||
  isTruthy(getEnvVariable('CLERK_KEYLESS_DISABLED')) ||
  false;
 
-export const canUseKeyless = isDevelopmentEnvironment() && !KEYLESS_DISABLED;
+export const canUseKeyless = isDevelopmentEnvironment() && !isAutomatedEnvironment() && !KEYLESS_DISABLED;

packages/backend/src/api/__tests__/AccountlessApplicationsApi.test.ts

@@ -0,0 +1,99 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('AccountlessApplications', () => {
+ const mockAccountlessApplication = {
+ object: 'accountless_application',
+ publishable_key: 'pk_test_keyless',
+ secret_key: 'sk_test_keyless',
+ claim_url: 'https://dashboard.clerk.com/claim',
+ api_keys_url: 'https://dashboard.clerk.com/api-keys',
+ };
+
+ it('creates an accountless application with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('creates an accountless application without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+});

packages/backend/src/api/endpoints/AccountlessApplicationsAPI.ts

@@ -4,22 +4,35 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/accountless_applications';
 
+type AccountlessApplicationParams = {
+ requestHeaders?: Headers;
+ source?: string;
+};
+
 export class AccountlessApplicationAPI extends AbstractAPI {
- public async createAccountlessApplication(params?: { requestHeaders?: Headers }) {
+ public async createAccountlessApplication(params?: AccountlessApplicationParams): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: basePath,
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 
- public async completeAccountlessApplicationOnboarding(params?: { requestHeaders?: Headers }) {
+ public async completeAccountlessApplicationOnboarding(
+ params?: AccountlessApplicationParams,
+ ): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: joinPaths(basePath, 'complete'),
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 }

packages/nextjs/src/server/keyless-node.ts

@@ -24,19 +24,21 @@ export function keyless() {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

.changeset/keyless-ci-guard.md

@@ -0,0 +1,11 @@
+---
+'@clerk/astro': patch
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+'@clerk/nuxt': patch
+'@clerk/react-router': patch
+'@clerk/shared': patch
+'@clerk/tanstack-react-start': patch
+---
+
+Prevent keyless mode from activating in CI and other automated environments in framework SDKs.

integration/models/__tests__/application.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { resolveServerUrl } from '../application';
+import { createAppRuntimeEnv, resolveServerUrl } from '../application';
+import { environmentConfig } from '../environment';
 
 describe('resolveServerUrl', () => {
  describe('with opts.serverUrl', () => {
@@ -49,3 +50,16 @@ describe('resolveServerUrl', () => {
  });
  });
 });
+
+describe('createAppRuntimeEnv', () => {
+ it('passes configured falsey values through to spawned app processes', () => {
+ const env = environmentConfig()
+ .setEnvVariable('private', 'CI', 'false')
+ .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
+
+ expect(createAppRuntimeEnv(env)).toMatchObject({
+ CI: 'false',
+ CLERK_KEYLESS_DISABLED: 'false',
+ });
+ });
+});

integration/models/application.ts

@@ -34,6 +34,24 @@ export const resolveServerUrl = (
  return fallbackServerUrl || `http://localhost:${port}`;
 };
 
+export const createAppRuntimeEnv = (env?: EnvironmentConfig): Record<string, string> => {
+ if (!env?.publicVariables || !env?.privateVariables) {
+ return {};
+ }
+
+ const runtimeEnv: Record<string, string> = {};
+ // Private variables intentionally win when the same runtime key exists in both maps.
+ for (const [key, value] of [...env.publicVariables, ...env.privateVariables]) {
+ if (value === undefined || value === null) {
+ continue;
+ }
+
+ runtimeEnv[key] = String(value);
+ }
+
+ return runtimeEnv;
+};
+
 export const application = (
  config: ApplicationConfig,
  appDirPath: string,
@@ -103,7 +121,7 @@ export const application = (
 
  const proc = run(scripts.dev, {
  cwd: appDirPath,
- env: { PORT: port.toString() },
+ env: { ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,
@@ -158,6 +176,7 @@ export const application = (
  const log = logger.child({ prefix: 'build' }).info;
  await run(scripts.build, {
  cwd: appDirPath,
+ env: createAppRuntimeEnv(state.env),
  log: (msg: string) => {
  buildOutput += `\n${msg}`;
  log(msg);
@@ -200,7 +219,7 @@ export const application = (
 
  const proc = run(scripts.serve, {
  cwd: appDirPath,
- env: { ...envFromFile, PORT: port.toString() },
+ env: { ...envFromFile, ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,

integration/presets/envs.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
 import fs from 'fs-extra';
 
 import { constants } from '../constants';
@@ -91,6 +92,10 @@ const withKeyless = base
  .setEnvVariable('private', 'CLERK_API_URL', 'https://api.clerkstage.dev')
  .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
 
+automatedEnvironmentVariables.forEach(name => {
+ withKeyless.setEnvVariable('private', name, 'false');
+});
+
 const withEmailCodes = withInstanceKeys(
  'with-email-codes',
  base

packages/astro/src/server/keyless/index.ts

@@ -12,21 +12,23 @@ export function keyless(context: APIContext) {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(context).__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(
  context,
  ).__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

packages/astro/src/utils/__tests__/feature-flags.test.ts

@@ -0,0 +1,48 @@
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+async function loadCanUseKeyless() {
+ vi.resetModules();
+ const { canUseKeyless } = await import('../feature-flags.js');
+ return canUseKeyless;
+}
+
+describe('canUseKeyless', () => {
+ beforeEach(() => {
+ vi.stubEnv('NODE_ENV', 'development');
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', undefined);
+ vi.stubEnv('CLERK_KEYLESS_DISABLED', undefined);
+ automatedEnvironmentVariables.forEach(name => {
+ vi.stubEnv(name, undefined);
+ vi.stubGlobal(name, undefined);
+ });
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ vi.resetModules();
+ });
+
+ it('enables keyless in development when automation signals are absent', async () => {
+ await expect(loadCanUseKeyless()).resolves.toBe(true);
+ });
+
+ it('disables keyless in CI even when the app runs in development mode', async () => {
+ vi.stubEnv('CI', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless outside development mode', async () => {
+ vi.stubEnv('NODE_ENV', 'production');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless when explicitly disabled', async () => {
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+});

packages/astro/src/utils/feature-flags.ts

@@ -1,10 +1,10 @@
 import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { isTruthy } from '@clerk/shared/underscore';
-import { isDevelopmentEnvironment } from '@clerk/shared/utils';
+import { isAutomatedEnvironment, isDevelopmentEnvironment } from '@clerk/shared/utils';
 
 const KEYLESS_DISABLED =
  isTruthy(getEnvVariable('PUBLIC_CLERK_KEYLESS_DISABLED')) ||
  isTruthy(getEnvVariable('CLERK_KEYLESS_DISABLED')) ||
  false;
 
-export const canUseKeyless = isDevelopmentEnvironment() && !KEYLESS_DISABLED;
+export const canUseKeyless = isDevelopmentEnvironment() && !isAutomatedEnvironment() && !KEYLESS_DISABLED;

packages/backend/src/api/__tests__/AccountlessApplicationsApi.test.ts

@@ -0,0 +1,99 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('AccountlessApplications', () => {
+ const mockAccountlessApplication = {
+ object: 'accountless_application',
+ publishable_key: 'pk_test_keyless',
+ secret_key: 'sk_test_keyless',
+ claim_url: 'https://dashboard.clerk.com/claim',
+ api_keys_url: 'https://dashboard.clerk.com/api-keys',
+ };
+
+ it('creates an accountless application with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('creates an accountless application without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+});

packages/backend/src/api/endpoints/AccountlessApplicationsAPI.ts

@@ -4,22 +4,35 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/accountless_applications';
 
+type AccountlessApplicationParams = {
+ requestHeaders?: Headers;
+ source?: string;
+};
+
 export class AccountlessApplicationAPI extends AbstractAPI {
- public async createAccountlessApplication(params?: { requestHeaders?: Headers }) {
+ public async createAccountlessApplication(params?: AccountlessApplicationParams): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: basePath,
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 
- public async completeAccountlessApplicationOnboarding(params?: { requestHeaders?: Headers }) {
+ public async completeAccountlessApplicationOnboarding(
+ params?: AccountlessApplicationParams,
+ ): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: joinPaths(basePath, 'complete'),
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 }

packages/nextjs/src/server/keyless-node.ts

@@ -24,19 +24,21 @@ export function keyless() {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

.changeset/keyless-ci-guard.md

@@ -0,0 +1,11 @@
+---
+'@clerk/astro': patch
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+'@clerk/nuxt': patch
+'@clerk/react-router': patch
+'@clerk/shared': patch
+'@clerk/tanstack-react-start': patch
+---
+
+Prevent keyless mode from activating in CI and other automated environments in framework SDKs.

integration/models/__tests__/application.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { resolveServerUrl } from '../application';
+import { createAppRuntimeEnv, resolveServerUrl } from '../application';
+import { environmentConfig } from '../environment';
 
 describe('resolveServerUrl', () => {
  describe('with opts.serverUrl', () => {
@@ -49,3 +50,16 @@ describe('resolveServerUrl', () => {
  });
  });
 });
+
+describe('createAppRuntimeEnv', () => {
+ it('passes configured falsey values through to spawned app processes', () => {
+ const env = environmentConfig()
+ .setEnvVariable('private', 'CI', 'false')
+ .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
+
+ expect(createAppRuntimeEnv(env)).toMatchObject({
+ CI: 'false',
+ CLERK_KEYLESS_DISABLED: 'false',
+ });
+ });
+});

integration/models/application.ts

@@ -34,6 +34,24 @@ export const resolveServerUrl = (
  return fallbackServerUrl || `http://localhost:${port}`;
 };
 
+export const createAppRuntimeEnv = (env?: EnvironmentConfig): Record<string, string> => {
+ if (!env?.publicVariables || !env?.privateVariables) {
+ return {};
+ }
+
+ const runtimeEnv: Record<string, string> = {};
+ // Private variables intentionally win when the same runtime key exists in both maps.
+ for (const [key, value] of [...env.publicVariables, ...env.privateVariables]) {
+ if (value === undefined || value === null) {
+ continue;
+ }
+
+ runtimeEnv[key] = String(value);
+ }
+
+ return runtimeEnv;
+};
+
 export const application = (
  config: ApplicationConfig,
  appDirPath: string,
@@ -103,7 +121,7 @@ export const application = (
 
  const proc = run(scripts.dev, {
  cwd: appDirPath,
- env: { PORT: port.toString() },
+ env: { ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,
@@ -158,6 +176,7 @@ export const application = (
  const log = logger.child({ prefix: 'build' }).info;
  await run(scripts.build, {
  cwd: appDirPath,
+ env: createAppRuntimeEnv(state.env),
  log: (msg: string) => {
  buildOutput += `\n${msg}`;
  log(msg);
@@ -200,7 +219,7 @@ export const application = (
 
  const proc = run(scripts.serve, {
  cwd: appDirPath,
- env: { ...envFromFile, PORT: port.toString() },
+ env: { ...envFromFile, ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,

integration/presets/envs.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
 import fs from 'fs-extra';
 
 import { constants } from '../constants';
@@ -91,6 +92,10 @@ const withKeyless = base
  .setEnvVariable('private', 'CLERK_API_URL', 'https://api.clerkstage.dev')
  .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
 
+automatedEnvironmentVariables.forEach(name => {
+ withKeyless.setEnvVariable('private', name, 'false');
+});
+
 const withEmailCodes = withInstanceKeys(
  'with-email-codes',
  base

packages/astro/src/server/keyless/index.ts

@@ -12,21 +12,23 @@ export function keyless(context: APIContext) {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(context).__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(
  context,
  ).__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

packages/astro/src/utils/__tests__/feature-flags.test.ts

@@ -0,0 +1,48 @@
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+async function loadCanUseKeyless() {
+ vi.resetModules();
+ const { canUseKeyless } = await import('../feature-flags.js');
+ return canUseKeyless;
+}
+
+describe('canUseKeyless', () => {
+ beforeEach(() => {
+ vi.stubEnv('NODE_ENV', 'development');
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', undefined);
+ vi.stubEnv('CLERK_KEYLESS_DISABLED', undefined);
+ automatedEnvironmentVariables.forEach(name => {
+ vi.stubEnv(name, undefined);
+ vi.stubGlobal(name, undefined);
+ });
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ vi.resetModules();
+ });
+
+ it('enables keyless in development when automation signals are absent', async () => {
+ await expect(loadCanUseKeyless()).resolves.toBe(true);
+ });
+
+ it('disables keyless in CI even when the app runs in development mode', async () => {
+ vi.stubEnv('CI', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless outside development mode', async () => {
+ vi.stubEnv('NODE_ENV', 'production');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless when explicitly disabled', async () => {
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+});

packages/astro/src/utils/feature-flags.ts

@@ -1,10 +1,10 @@
 import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { isTruthy } from '@clerk/shared/underscore';
-import { isDevelopmentEnvironment } from '@clerk/shared/utils';
+import { isAutomatedEnvironment, isDevelopmentEnvironment } from '@clerk/shared/utils';
 
 const KEYLESS_DISABLED =
  isTruthy(getEnvVariable('PUBLIC_CLERK_KEYLESS_DISABLED')) ||
  isTruthy(getEnvVariable('CLERK_KEYLESS_DISABLED')) ||
  false;
 
-export const canUseKeyless = isDevelopmentEnvironment() && !KEYLESS_DISABLED;
+export const canUseKeyless = isDevelopmentEnvironment() && !isAutomatedEnvironment() && !KEYLESS_DISABLED;

packages/backend/src/api/__tests__/AccountlessApplicationsApi.test.ts

@@ -0,0 +1,99 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('AccountlessApplications', () => {
+ const mockAccountlessApplication = {
+ object: 'accountless_application',
+ publishable_key: 'pk_test_keyless',
+ secret_key: 'sk_test_keyless',
+ claim_url: 'https://dashboard.clerk.com/claim',
+ api_keys_url: 'https://dashboard.clerk.com/api-keys',
+ };
+
+ it('creates an accountless application with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('creates an accountless application without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+});

packages/backend/src/api/endpoints/AccountlessApplicationsAPI.ts

@@ -4,22 +4,35 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/accountless_applications';
 
+type AccountlessApplicationParams = {
+ requestHeaders?: Headers;
+ source?: string;
+};
+
 export class AccountlessApplicationAPI extends AbstractAPI {
- public async createAccountlessApplication(params?: { requestHeaders?: Headers }) {
+ public async createAccountlessApplication(params?: AccountlessApplicationParams): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: basePath,
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 
- public async completeAccountlessApplicationOnboarding(params?: { requestHeaders?: Headers }) {
+ public async completeAccountlessApplicationOnboarding(
+ params?: AccountlessApplicationParams,
+ ): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: joinPaths(basePath, 'complete'),
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 }

packages/nextjs/src/server/keyless-node.ts

@@ -24,19 +24,21 @@ export function keyless() {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

.changeset/keyless-ci-guard.md

@@ -0,0 +1,11 @@
+---
+'@clerk/astro': patch
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+'@clerk/nuxt': patch
+'@clerk/react-router': patch
+'@clerk/shared': patch
+'@clerk/tanstack-react-start': patch
+---
+
+Prevent keyless mode from activating in CI and other automated environments in framework SDKs.

integration/models/__tests__/application.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { resolveServerUrl } from '../application';
+import { createAppRuntimeEnv, resolveServerUrl } from '../application';
+import { environmentConfig } from '../environment';
 
 describe('resolveServerUrl', () => {
  describe('with opts.serverUrl', () => {
@@ -49,3 +50,16 @@ describe('resolveServerUrl', () => {
  });
  });
 });
+
+describe('createAppRuntimeEnv', () => {
+ it('passes configured falsey values through to spawned app processes', () => {
+ const env = environmentConfig()
+ .setEnvVariable('private', 'CI', 'false')
+ .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
+
+ expect(createAppRuntimeEnv(env)).toMatchObject({
+ CI: 'false',
+ CLERK_KEYLESS_DISABLED: 'false',
+ });
+ });
+});

integration/models/application.ts

@@ -34,6 +34,24 @@ export const resolveServerUrl = (
  return fallbackServerUrl || `http://localhost:${port}`;
 };
 
+export const createAppRuntimeEnv = (env?: EnvironmentConfig): Record<string, string> => {
+ if (!env?.publicVariables || !env?.privateVariables) {
+ return {};
+ }
+
+ const runtimeEnv: Record<string, string> = {};
+ // Private variables intentionally win when the same runtime key exists in both maps.
+ for (const [key, value] of [...env.publicVariables, ...env.privateVariables]) {
+ if (value === undefined || value === null) {
+ continue;
+ }
+
+ runtimeEnv[key] = String(value);
+ }
+
+ return runtimeEnv;
+};
+
 export const application = (
  config: ApplicationConfig,
  appDirPath: string,
@@ -103,7 +121,7 @@ export const application = (
 
  const proc = run(scripts.dev, {
  cwd: appDirPath,
- env: { PORT: port.toString() },
+ env: { ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,
@@ -158,6 +176,7 @@ export const application = (
  const log = logger.child({ prefix: 'build' }).info;
  await run(scripts.build, {
  cwd: appDirPath,
+ env: createAppRuntimeEnv(state.env),
  log: (msg: string) => {
  buildOutput += `\n${msg}`;
  log(msg);
@@ -200,7 +219,7 @@ export const application = (
 
  const proc = run(scripts.serve, {
  cwd: appDirPath,
- env: { ...envFromFile, PORT: port.toString() },
+ env: { ...envFromFile, ...createAppRuntimeEnv(state.env), PORT: port.toString() },
  detached: opts.detached,
  stdout: opts.detached ? fs.openSync(stdoutFilePath, 'a') : undefined,
  stderr: opts.detached ? fs.openSync(stderrFilePath, 'a') : undefined,

integration/presets/envs.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
 import fs from 'fs-extra';
 
 import { constants } from '../constants';
@@ -91,6 +92,10 @@ const withKeyless = base
  .setEnvVariable('private', 'CLERK_API_URL', 'https://api.clerkstage.dev')
  .setEnvVariable('public', 'CLERK_KEYLESS_DISABLED', false);
 
+automatedEnvironmentVariables.forEach(name => {
+ withKeyless.setEnvVariable('private', name, 'false');
+});
+
 const withEmailCodes = withInstanceKeys(
  'with-email-codes',
  base

packages/astro/src/server/keyless/index.ts

@@ -12,21 +12,23 @@ export function keyless(context: APIContext) {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(context).__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await clerkClient(
  context,
  ).__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;

packages/astro/src/utils/__tests__/feature-flags.test.ts

@@ -0,0 +1,48 @@
+import { automatedEnvironmentVariables } from '@clerk/shared/utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+async function loadCanUseKeyless() {
+ vi.resetModules();
+ const { canUseKeyless } = await import('../feature-flags.js');
+ return canUseKeyless;
+}
+
+describe('canUseKeyless', () => {
+ beforeEach(() => {
+ vi.stubEnv('NODE_ENV', 'development');
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', undefined);
+ vi.stubEnv('CLERK_KEYLESS_DISABLED', undefined);
+ automatedEnvironmentVariables.forEach(name => {
+ vi.stubEnv(name, undefined);
+ vi.stubGlobal(name, undefined);
+ });
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ vi.resetModules();
+ });
+
+ it('enables keyless in development when automation signals are absent', async () => {
+ await expect(loadCanUseKeyless()).resolves.toBe(true);
+ });
+
+ it('disables keyless in CI even when the app runs in development mode', async () => {
+ vi.stubEnv('CI', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless outside development mode', async () => {
+ vi.stubEnv('NODE_ENV', 'production');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+
+ it('disables keyless when explicitly disabled', async () => {
+ vi.stubEnv('PUBLIC_CLERK_KEYLESS_DISABLED', 'true');
+
+ await expect(loadCanUseKeyless()).resolves.toBe(false);
+ });
+});

packages/astro/src/utils/feature-flags.ts

@@ -1,10 +1,10 @@
 import { getEnvVariable } from '@clerk/shared/getEnvVariable';
 import { isTruthy } from '@clerk/shared/underscore';
-import { isDevelopmentEnvironment } from '@clerk/shared/utils';
+import { isAutomatedEnvironment, isDevelopmentEnvironment } from '@clerk/shared/utils';
 
 const KEYLESS_DISABLED =
  isTruthy(getEnvVariable('PUBLIC_CLERK_KEYLESS_DISABLED')) ||
  isTruthy(getEnvVariable('CLERK_KEYLESS_DISABLED')) ||
  false;
 
-export const canUseKeyless = isDevelopmentEnvironment() && !KEYLESS_DISABLED;
+export const canUseKeyless = isDevelopmentEnvironment() && !isAutomatedEnvironment() && !KEYLESS_DISABLED;

packages/backend/src/api/__tests__/AccountlessApplicationsApi.test.ts

@@ -0,0 +1,99 @@
+import { http, HttpResponse } from 'msw';
+import { describe, expect, it } from 'vitest';
+
+import { server } from '../../mock-server';
+import { createBackendApiClient } from '../factory';
+
+describe('AccountlessApplications', () => {
+ const mockAccountlessApplication = {
+ object: 'accountless_application',
+ publishable_key: 'pk_test_keyless',
+ secret_key: 'sk_test_keyless',
+ claim_url: 'https://dashboard.clerk.com/claim',
+ api_keys_url: 'https://dashboard.clerk.com/api-keys',
+ };
+
+ it('creates an accountless application with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('creates an accountless application without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.createAccountlessApplication();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding with a source query parameter', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.get('source')).toBe('nextjs');
+ expect(request.headers.get('Clerk-API-Version')).toBeTruthy();
+ expect(request.headers.get('User-Agent')).toBe('@clerk/backend@0.0.0-test');
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+ source: 'nextjs',
+ });
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+
+ it('completes accountless application onboarding without a source query parameter when source is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ });
+
+ server.use(
+ http.post('https://api.clerk.test/v1/accountless_applications/complete', ({ request }) => {
+ const url = new URL(request.url);
+ expect(url.searchParams.has('source')).toBe(false);
+
+ return HttpResponse.json(mockAccountlessApplication);
+ }),
+ );
+
+ const response = await apiClient.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding();
+
+ expect(response.publishableKey).toBe('pk_test_keyless');
+ });
+});

packages/backend/src/api/endpoints/AccountlessApplicationsAPI.ts

@@ -4,22 +4,35 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/accountless_applications';
 
+type AccountlessApplicationParams = {
+ requestHeaders?: Headers;
+ source?: string;
+};
+
 export class AccountlessApplicationAPI extends AbstractAPI {
- public async createAccountlessApplication(params?: { requestHeaders?: Headers }) {
+ public async createAccountlessApplication(params?: AccountlessApplicationParams): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: basePath,
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 
- public async completeAccountlessApplicationOnboarding(params?: { requestHeaders?: Headers }) {
+ public async completeAccountlessApplicationOnboarding(
+ params?: AccountlessApplicationParams,
+ ): Promise<AccountlessApplication> {
  const headerParams = params?.requestHeaders ? Object.fromEntries(params.requestHeaders.entries()) : undefined;
  return this.request<AccountlessApplication>({
  method: 'POST',
  path: joinPaths(basePath, 'complete'),
  headerParams,
+ queryParams: {
+ source: params?.source,
+ },
  });
  }
 }

packages/nextjs/src/server/keyless-node.ts

@@ -24,19 +24,21 @@ export function keyless() {
  keylessServiceInstance = createKeylessService({
  storage: createFileStorage(),
  api: {
- async createAccountlessApplication(requestHeaders?: Headers) {
+ async createAccountlessApplication(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.createAccountlessApplication({
  requestHeaders,
+ source,
  });
  } catch {
  return null;
  }
  },
- async completeOnboarding(requestHeaders?: Headers) {
+ async completeOnboarding(requestHeaders?: Headers, source?: string) {
  try {
  return await client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
  requestHeaders,
+ source,
  });
  } catch {
  return null;