feat(astro): throw missing-env error instead of keyless bootstrap

.changeset/astro-keyless-cli-init-error.md

@@ -0,0 +1,6 @@
+---
+'@clerk/astro': minor
+'@clerk/shared': patch
+---
+
+In development, missing Clerk keys no longer activate keyless mode. When `PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` are not set, the SDK now fails with an error directing you to run `npx clerk@latest init`, which provisions a Clerk application and writes the keys to `.env`. Existing apps with configured or claimed keys are unaffected.

integration/tests/astro/keyless.test.ts

@@ -1,12 +1,11 @@
-import { test } from '@playwright/test';
+import * as path from 'node:path';
+
+import { expect, test } from '@playwright/test';
 
 import type { Application } from '../../models/application';
 import { appConfigs } from '../../presets';
-import {
-  testClaimedAppWithMissingKeys,
-  testKeylessRemovedAfterEnvAndRestart,
-  testToggleCollapsePopoverAndClaim,
-} from '../../testUtils/keylessHelpers';
+import { fs } from '../../scripts';
+import { createTestUtils } from '../../testUtils';
 
 const commonSetup = appConfigs.astro.node.clone();
 
@@ -21,34 +20,54 @@ test.describe('Keyless mode @astro', () => {
   });
 
   let app: Application;
-  let dashboardUrl = 'https://dashboard.clerk.com/';
 
   test.beforeAll(async () => {
     app = await commonSetup.commit();
     await app.setup();
     await app.withEnv(appConfigs.envs.withKeyless);
-    if (appConfigs.envs.withKeyless.privateVariables.get('CLERK_API_URL')?.includes('clerkstage')) {
-      dashboardUrl = 'https://dashboard.clerkstage.dev/';
-    }
-    await app.dev();
+    // Without keys the app 500s on every request, so readiness can't wait for a 2xx
+    await app.dev({ acceptAnyResponse: true });
   });
 
   test.afterAll(async () => {
     await app?.teardown();
   });
 
-  test('Toggle collapse popover and claim.', async ({ page, context }) => {
-    await testToggleCollapsePopoverAndClaim({ page, context, app, dashboardUrl, framework: 'astro' });
-  });
-
-  test('Lands on claimed application with missing explicit keys, expanded by default, click to get keys from dashboard.', async ({
+  test('Without keys, requests fail with the missing env vars error instead of keyless bootstrap.', async ({
     page,
-    context,
   }) => {
-    await testClaimedAppWithMissingKeys({ page, context, app, dashboardUrl });
+    const response = await page.goto(`${app.serverUrl}/`);
+    expect(response?.status()).toBe(500);
+    // The Astro dev error overlay renders inside shadow DOM, which page.content() does not
+    // include — locators pierce open shadow roots.
+    await expect(page.getByText('Publishable key is missing').first()).toBeVisible();
+    await expect(page.getByText('npx clerk@latest init').first()).toBeVisible();
   });
 
-  test('Keyless popover is removed after adding keys to .env and restarting.', async ({ page, context }) => {
-    await testKeylessRemovedAfterEnvAndRestart({ page, context, app });
+  test('Claimed application with keys inside .env boots and serves the app.', async ({ page, context }) => {
+    /**
+     * Seed claimed keyless state directly: the SDK no longer mints keys, so write the
+     * keys fixture to `.clerk/.tmp/keyless.json` and configure the matching environment
+     * (keys AND api url, so the server-side onboarding-completion call targets the right
+     * instance). The completion request itself is BAPI-bound from the server, invisible
+     * to Playwright — its logic is covered by packages/astro keyless unit tests.
+     */
+    const publishableKey = appConfigs.envs.withEmailCodes.publicVariables.get('CLERK_PUBLISHABLE_KEY');
+    const secretKey = appConfigs.envs.withEmailCodes.privateVariables.get('CLERK_SECRET_KEY');
+    await fs.ensureDir(path.join(app.appDir, '.clerk', '.tmp'));
+    await fs.writeJSON(path.join(app.appDir, '.clerk', '.tmp', 'keyless.json'), {
+      publishableKey,
+      secretKey,
+      claimUrl: 'https://dashboard.clerk.com/apps/claim',
+      apiKeysUrl: 'https://dashboard.clerk.com/last-active?path=api-keys',
+    });
+    await app.withEnv(appConfigs.envs.withEmailCodes);
+    // Restart the dev server to pick up new env vars (Vite doesn't hot-reload .env)
+    await app.restart();
+
+    const u = createTestUtils({ app, page, context });
+    await u.page.goToAppHome();
+    await u.page.waitForClerkJsLoaded();
+    await u.po.expect.toBeSignedOut();
   });
 });

packages/astro/src/env.d.ts

@@ -31,9 +31,6 @@ interface ImportMeta {
 declare namespace App {
   interface Locals {
     runtime?: { env: InternalEnv };
-    keylessClaimUrl?: string;
-    keylessApiKeysUrl?: string;
-    keylessPublishableKey?: string;
   }
 }
 

packages/astro/src/internal/create-clerk-instance.ts

@@ -9,7 +9,7 @@ import type { Ui } from '@clerk/ui/internal';
 
 import { $clerkStore } from '../stores/external';
 import { $clerk, $csrState } from '../stores/internal';
-import type { AstroClerkCreateInstanceParams, AstroClerkUpdateOptions, InternalRuntimeOptions } from '../types';
+import type { AstroClerkCreateInstanceParams, AstroClerkUpdateOptions } from '../types';
 import { invokeClerkAstroJSFunctions } from './invoke-clerk-astro-js-functions';
 import { mountAllClerkAstroJSComponents } from './mount-clerk-astro-js-components';
 import { runOnce } from './run-once';
@@ -54,18 +54,12 @@ async function createClerkInstanceInternal<TUi extends Ui = Ui>(options?: AstroC
     $clerk.set(clerkJSInstance);
   }
 
-  const internalOptions = options as AstroClerkCreateInstanceParams<TUi> & InternalRuntimeOptions;
-  const keylessClaimUrl = internalOptions.__internal_keylessClaimUrl;
-  const keylessApiKeysUrl = internalOptions.__internal_keylessApiKeysUrl;
-
   const clerkOptions = {
     routerPush: createNavigationHandler(window.history.pushState.bind(window.history)),
     routerReplace: createNavigationHandler(window.history.replaceState.bind(window.history)),
     ...options,
     // Pass the clerk-ui constructor promise to clerk.load()
     ui: { ...options?.ui, ClerkUI },
-    ...(keylessClaimUrl && { __internal_keyless_claimKeylessApplicationUrl: keylessClaimUrl }),
-    ...(keylessApiKeysUrl && { __internal_keyless_copyInstanceKeysUrl: keylessApiKeysUrl }),
   } as unknown as ClerkOptions;
 
   initOptions = clerkOptions;

packages/astro/src/internal/merge-env-vars-with-params.ts

@@ -1,7 +1,7 @@
 import type { InternalClerkScriptProps } from '@clerk/shared/types';
 import { isTruthy } from '@clerk/shared/underscore';
 
-import type { AstroClerkIntegrationParams, InternalRuntimeOptions } from '../types';
+import type { AstroClerkIntegrationParams } from '../types';
 
 /**
  * Merges `prefetchUI` param with env vars.
@@ -27,7 +27,7 @@ function mergePrefetchUIConfig(paramPrefetchUI: AstroClerkIntegrationParams['pre
  * @internal
  */
 const mergeEnvVarsWithParams = (
-  params?: AstroClerkIntegrationParams & InternalRuntimeOptions & InternalClerkScriptProps,
+  params?: AstroClerkIntegrationParams & { publishableKey?: string } & InternalClerkScriptProps,
 ) => {
   const {
     signInUrl: paramSignIn,
@@ -46,17 +46,13 @@ const mergeEnvVarsWithParams = (
     ...rest
   } = params || {};
 
-  const internalOptions = params;
-
   return {
     signInUrl: paramSignIn || import.meta.env.PUBLIC_CLERK_SIGN_IN_URL,
     signUpUrl: paramSignUp || import.meta.env.PUBLIC_CLERK_SIGN_UP_URL,
     isSatellite: paramSatellite || import.meta.env.PUBLIC_CLERK_IS_SATELLITE,
     proxyUrl: paramProxy || import.meta.env.PUBLIC_CLERK_PROXY_URL,
     domain: paramDomain || import.meta.env.PUBLIC_CLERK_DOMAIN,
-    // In keyless mode, use server-injected publishableKey from params
-    publishableKey:
-      paramPublishableKey || internalOptions?.publishableKey || import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY || '',
+    publishableKey: paramPublishableKey || import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY || '',
     __internal_clerkJSUrl: paramClerkJSUrl || import.meta.env.PUBLIC_CLERK_JS_URL,
     __internal_clerkJSVersion: paramClerkJSVersion || import.meta.env.PUBLIC_CLERK_JS_VERSION,
     __internal_clerkUIUrl: paramClerkUIUrl || import.meta.env.PUBLIC_CLERK_UI_URL,
@@ -69,10 +65,6 @@ const mergeEnvVarsWithParams = (
     unsafe_disableDevelopmentModeConsoleWarning:
       paramUnsafeDisableDevelopmentModeConsoleWarning ??
       isTruthy(import.meta.env.PUBLIC_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING),
-    // Read from params (server-injected via __CLERK_ASTRO_SAFE_VARS__)
-    // These are dynamically resolved by middleware, not from env vars
-    __internal_keylessClaimUrl: internalOptions?.keylessClaimUrl,
-    __internal_keylessApiKeysUrl: internalOptions?.keylessApiKeysUrl,
     ...rest,
   };
 };

packages/astro/src/server/__tests__/get-safe-env.test.ts

@@ -211,20 +211,6 @@ describe('getSafeEnv', () => {
     expect(env.pk).toBeUndefined();
     expect(env.sk).toBeUndefined();
   });
-
-  it('prefers keylessPublishableKey over all env sources', () => {
-    process.env.PUBLIC_CLERK_PUBLISHABLE_KEY = 'pk_from_process';
-
-    const locals = createLocals({
-      runtime: { env: undefined as unknown as InternalEnv },
-      keylessPublishableKey: 'pk_keyless',
-    });
-    const env = getSafeEnv(locals);
-
-    expect(env.pk).toBe('pk_keyless');
-
-    delete process.env.PUBLIC_CLERK_PUBLISHABLE_KEY;
-  });
 });
 
 describe('getClientSafeEnv', () => {

packages/astro/src/server/clerk-middleware.ts

@@ -32,7 +32,7 @@ import { buildClerkHotloadScript } from './build-clerk-hotload-script';
 import { clerkClient } from './clerk-client';
 import { createCurrentUser } from './current-user';
 import { getClientSafeEnv, getSafeEnv, initCloudflareEnv } from './get-safe-env';
-import { resolveKeysWithKeylessFallback } from './keyless/utils';
+import { completeOnboardingIfClaimed } from './keyless/utils';
 import { serverRedirectWithAuth } from './server-redirect-with-auth';
 import type {
   AstroMiddleware,
@@ -87,42 +87,18 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]): any => {
     const patchedRequest = patchRequest(context.request);
     const clerkRequest = createClerkRequest(patchedRequest);
 
-    // Resolve keyless URLs per-request in development
-    let keylessClaimUrl: string | undefined;
-    let keylessApiKeysUrl: string | undefined;
-    let keylessOptions = options;
-
     if (canUseKeyless) {
       try {
         const env = getSafeEnv(context);
-        const configuredPublishableKey = options?.publishableKey || env.pk;
-        const configuredSecretKey = options?.secretKey || env.sk;
-
-        const keylessResult = await resolveKeysWithKeylessFallback(
-          configuredPublishableKey,
-          configuredSecretKey,
-          context,
-        );
-
-        keylessClaimUrl = keylessResult.claimUrl;
-        keylessApiKeysUrl = keylessResult.apiKeysUrl;
-
-        // Override keys with keyless values if returned
-        if (keylessResult.publishableKey || keylessResult.secretKey) {
-          keylessOptions = {
-            ...options,
-            ...(keylessResult.publishableKey && { publishableKey: keylessResult.publishableKey }),
-            ...(keylessResult.secretKey && { secretKey: keylessResult.secretKey }),
-          };
-        }
+        await completeOnboardingIfClaimed(options?.publishableKey || env.pk, context);
       } catch {
-        // Silently fail - continue without keyless
+        // Silently fail - claimed-keys onboarding must not break requests
       }
     }
 
     const requestState = await clerkClient(context).authenticateRequest(
       clerkRequest,
-      createAuthenticateRequestOptions(clerkRequest, keylessOptions, context),
+      createAuthenticateRequestOptions(clerkRequest, options, context),
     );
 
     const locationHeader = requestState.headers.get(constants.Headers.Location);
@@ -145,16 +121,6 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]): any => {
 
     decorateAstroLocal(clerkRequest, authObjectFn, context, requestState);
 
-    // Store keyless data for injection into client
-    if (keylessClaimUrl || keylessApiKeysUrl) {
-      context.locals.keylessClaimUrl = keylessClaimUrl;
-      context.locals.keylessApiKeysUrl = keylessApiKeysUrl;
-      // Also store the resolved publishable key so client can use it
-      if (keylessOptions?.publishableKey) {
-        context.locals.keylessPublishableKey = keylessOptions.publishableKey;
-      }
-    }
-
     /**
      * ALS is crucial for guaranteeing SSR in UI frameworks like React.
      * This currently powers the `useAuth()` React hook and any other hook or Component that depends on it.

packages/astro/src/server/get-safe-env.ts

@@ -73,14 +73,11 @@ function getContextEnvVar(envVarName: keyof InternalEnv, contextOrLocals: Contex
  * @internal
  */
 function getSafeEnv(context: ContextOrLocals) {
-  const locals = 'locals' in context ? context.locals : context;
-
   return {
     domain: getContextEnvVar('PUBLIC_CLERK_DOMAIN', context),
     isSatellite: getContextEnvVar('PUBLIC_CLERK_IS_SATELLITE', context) === 'true',
     proxyUrl: getContextEnvVar('PUBLIC_CLERK_PROXY_URL', context),
-    // Use keyless publishable key if available, otherwise read from env
-    pk: locals.keylessPublishableKey || getContextEnvVar('PUBLIC_CLERK_PUBLISHABLE_KEY', context),
+    pk: getContextEnvVar('PUBLIC_CLERK_PUBLISHABLE_KEY', context),
     sk: getContextEnvVar('CLERK_SECRET_KEY', context),
     machineSecretKey: getContextEnvVar('CLERK_MACHINE_SECRET_KEY', context),
     signInUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_IN_URL', context),
@@ -94,9 +91,6 @@ function getSafeEnv(context: ContextOrLocals) {
     apiUrl: getContextEnvVar('CLERK_API_URL', context),
     telemetryDisabled: isTruthy(getContextEnvVar('PUBLIC_CLERK_TELEMETRY_DISABLED', context)),
     telemetryDebug: isTruthy(getContextEnvVar('PUBLIC_CLERK_TELEMETRY_DEBUG', context)),
-    // Read from locals (set by middleware) instead of env vars
-    keylessClaimUrl: locals.keylessClaimUrl,
-    keylessApiKeysUrl: locals.keylessApiKeysUrl,
   };
 }
 
@@ -108,19 +102,13 @@ function getSafeEnv(context: ContextOrLocals) {
  * This is a way to get around it.
  */
 function getClientSafeEnv(context: ContextOrLocals) {
-  const locals = 'locals' in context ? context.locals : context;
-
   return {
     domain: getContextEnvVar('PUBLIC_CLERK_DOMAIN', context),
     isSatellite: getContextEnvVar('PUBLIC_CLERK_IS_SATELLITE', context) === 'true',
     proxyUrl: getContextEnvVar('PUBLIC_CLERK_PROXY_URL', context),
     signInUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_IN_URL', context),
     signUpUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_UP_URL', context),
-    // In keyless mode, pass the resolved publishable key to client
-    publishableKey: locals.keylessPublishableKey || getContextEnvVar('PUBLIC_CLERK_PUBLISHABLE_KEY', context),
-    // Read from locals (set by middleware) instead of env vars
-    keylessClaimUrl: locals.keylessClaimUrl,
-    keylessApiKeysUrl: locals.keylessApiKeysUrl,
+    publishableKey: getContextEnvVar('PUBLIC_CLERK_PUBLISHABLE_KEY', context),
   };
 }
 

packages/astro/src/server/keyless/__tests__/utils.test.ts

@@ -0,0 +1,78 @@
+import type { APIContext } from 'astro';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { completeOnboardingIfClaimed } from '../utils';
+
+const { completeClaimedOnboarding, log, readKeys, completeOnboarding } = vi.hoisted(() => ({
+  completeClaimedOnboarding: vi.fn(() => Promise.resolve()),
+  log: vi.fn(),
+  readKeys: vi.fn(),
+  completeOnboarding: vi.fn(),
+}));
+
+vi.mock('@clerk/shared/keyless', () => ({
+  completeClaimedOnboarding,
+  clerkDevelopmentCache: { log },
+}));
+
+vi.mock('../index', () => ({
+  keyless: () => ({ readKeys, completeOnboarding }),
+}));
+
+const context = {} as APIContext;
+
+const storedKeys = {
+  publishableKey: 'pk_test_stored',
+  secretKey: 'sk_test_stored',
+  claimUrl: 'https://dashboard.clerk.com/apps/claim',
+  apiKeysUrl: 'https://dashboard.clerk.com/last-active?path=api-keys',
+};
+
+describe('completeOnboardingIfClaimed', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('completes onboarding when the configured key matches the stored keyless keys', async () => {
+    readKeys.mockReturnValue(storedKeys);
+
+    await completeOnboardingIfClaimed('pk_test_stored', context);
+
+    expect(completeClaimedOnboarding).toHaveBeenCalledTimes(1);
+    expect(completeClaimedOnboarding).toHaveBeenCalledWith('pk_test_stored', expect.objectContaining({ readKeys }));
+  });
+
+  it('does nothing when the configured key does not match the stored keys', async () => {
+    readKeys.mockReturnValue(storedKeys);
+
+    await completeOnboardingIfClaimed('pk_test_other', context);
+
+    expect(completeClaimedOnboarding).not.toHaveBeenCalled();
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when no keyless keys are stored', async () => {
+    readKeys.mockReturnValue(undefined);
+
+    await completeOnboardingIfClaimed('pk_test_stored', context);
+
+    expect(completeClaimedOnboarding).not.toHaveBeenCalled();
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  it('logs a pointer to the stored keys when no key is configured, without completing onboarding', async () => {
+    readKeys.mockReturnValue(storedKeys);
+
+    await completeOnboardingIfClaimed(undefined, context);
+
+    expect(completeClaimedOnboarding).not.toHaveBeenCalled();
+    expect(log).toHaveBeenCalledTimes(1);
+    expect(log).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cacheKey: 'pk_test_stored_stored',
+        msg: expect.stringContaining('.clerk/.tmp/keyless.json'),
+      }),
+    );
+    expect(log).toHaveBeenCalledWith(expect.objectContaining({ msg: expect.stringContaining(storedKeys.claimUrl) }));
+  });
+});