feat(astro): [WIP] Add support for keyless mode

integration/testUtils/keylessHelpers.ts

@@ -0,0 +1,20 @@
+import type { Page } from '@playwright/test';
+
+/**
+ * Mocks the environment API call to return a claimed instance.
+ * Used in keyless mode tests to simulate an instance that has been claimed.
+ */
+export const mockClaimedInstanceEnvironmentCall = async (page: Page): Promise<void> => {
+  await page.route('*/**/v1/environment*', async route => {
+    const response = await route.fetch();
+    const json = await response.json();
+    const newJson = {
+      ...json,
+      auth_config: {
+        ...json.auth_config,
+        claimed_at: Date.now(),
+      },
+    };
+    await route.fulfill({ response, json: newJson });
+  });
+};

integration/tests/astro/keyless.test.ts

@@ -0,0 +1,115 @@
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import { createTestUtils } from '../../testUtils';
+import { mockClaimedInstanceEnvironmentCall } from '../../testUtils/keylessHelpers';
+
+const commonSetup = appConfigs.astro.node.clone();
+
+test.describe('Keyless mode @astro', () => {
+  test.describe.configure({ mode: 'serial' });
+  test.setTimeout(90_000);
+
+  test.use({
+    extraHTTPHeaders: {
+      'x-vercel-protection-bypass': process.env.VERCEL_AUTOMATION_BYPASS_SECRET || '',
+    },
+  });
+
+  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();
+  });
+
+  test.afterAll(async () => {
+    await app?.teardown();
+  });
+
+  test('Toggle collapse popover and claim.', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    await u.page.goToAppHome();
+    await u.page.waitForClerkJsLoaded();
+    await u.po.expect.toBeSignedOut();
+
+    await u.po.keylessPopover.waitForMounted();
+
+    expect(await u.po.keylessPopover.isExpanded()).toBe(false);
+    await u.po.keylessPopover.toggle();
+    expect(await u.po.keylessPopover.isExpanded()).toBe(true);
+
+    const claim = await u.po.keylessPopover.promptsToClaim();
+
+    const [newPage] = await Promise.all([context.waitForEvent('page'), claim.click()]);
+
+    await newPage.waitForLoadState();
+
+    await newPage.waitForURL(url => {
+      const urlToReturnTo = `${dashboardUrl}apps/claim?token=`;
+
+      const signUpForceRedirectUrl = url.searchParams.get('sign_up_force_redirect_url');
+
+      const signUpForceRedirectUrlCheck =
+        signUpForceRedirectUrl?.startsWith(urlToReturnTo) ||
+        (signUpForceRedirectUrl?.startsWith(`${dashboardUrl}prepare-account`) &&
+          signUpForceRedirectUrl?.includes(encodeURIComponent('apps/claim?token=')));
+
+      return (
+        url.pathname === '/apps/claim/sign-in' &&
+        url.searchParams.get('sign_in_force_redirect_url')?.startsWith(urlToReturnTo) &&
+        signUpForceRedirectUrlCheck
+      );
+    });
+  });
+
+  test('Lands on claimed application with missing explicit keys, expanded by default, click to get keys from dashboard.', async ({
+    page,
+    context,
+  }) => {
+    await mockClaimedInstanceEnvironmentCall(page);
+    const u = createTestUtils({ app, page, context });
+    await u.page.goToAppHome();
+    await u.page.waitForClerkJsLoaded();
+
+    await u.po.keylessPopover.waitForMounted();
+    expect(await u.po.keylessPopover.isExpanded()).toBe(true);
+    await expect(u.po.keylessPopover.promptToUseClaimedKeys()).toBeVisible();
+
+    const [newPage] = await Promise.all([
+      context.waitForEvent('page'),
+      u.po.keylessPopover.promptToUseClaimedKeys().click(),
+    ]);
+
+    await newPage.waitForLoadState();
+    await newPage.waitForURL(url => {
+      return url.href.startsWith(`${dashboardUrl}sign-in?redirect_url=${encodeURIComponent(dashboardUrl)}apps%2Fapp_`);
+    });
+  });
+
+  test('Keyless popover is removed after adding keys to .env and restarting.', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    await u.page.goToAppHome();
+
+    await u.po.keylessPopover.waitForMounted();
+    expect(await u.po.keylessPopover.isExpanded()).toBe(false);
+
+    // Copy keys from keyless.json to .env
+    await app.keylessToEnv();
+
+    // Restart the dev server to pick up new env vars (Astro doesn't hot-reload .env)
+    await app.restart();
+
+    await u.page.goToAppHome();
+
+    // Keyless popover should no longer be present since we now have explicit keys
+    await u.po.keylessPopover.waitForUnmounted();
+  });
+});

packages/astro/package.json

@@ -96,7 +96,8 @@
   },
   "devDependencies": {
     "@clerk/ui": "workspace:^",
-    "astro": "^5.15.9"
+    "astro": "^5.15.9",
+    "vite": "^7.1.0"
   },
   "peerDependencies": {
     "astro": "^4.15.0 || ^5.0.0"

packages/astro/src/env.d.ts

@@ -20,6 +20,7 @@ interface InternalEnv {
   readonly PUBLIC_CLERK_SIGN_UP_URL?: string;
   readonly PUBLIC_CLERK_TELEMETRY_DISABLED?: string;
   readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string;
+  readonly PUBLIC_CLERK_KEYLESS_DISABLED?: string;
 }
 
 interface ImportMeta {
@@ -29,6 +30,9 @@ interface ImportMeta {
 declare namespace App {
   interface Locals {
     runtime: { env: InternalEnv };
+    keylessClaimUrl?: string;
+    keylessApiKeysUrl?: string;
+    keylessPublishableKey?: string;
   }
 }
 

packages/astro/src/integration/create-integration.ts

@@ -31,12 +31,19 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
             logger.error('Missing adapter, please update your Astro config to use one.');
           }
 
+          const isDev = command === 'dev';
+
+          // Read keys from process.env for vite.define injection
+          // Note: Keyless mode is now handled by middleware per-request, not here
+          const envPublishableKey = process.env.PUBLIC_CLERK_PUBLISHABLE_KEY;
+          const envSecretKey = process.env.CLERK_SECRET_KEY;
+
           const internalParams: ClerkOptions = {
             ...params,
             sdkMetadata: {
               version: packageVersion,
               name: packageName,
-              environment: command === 'dev' ? 'development' : 'production',
+              environment: isDev ? 'development' : 'production',
             },
           };
 
@@ -58,6 +65,9 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
                 ...buildEnvVarFromOption(clerkJSUrl, 'PUBLIC_CLERK_JS_URL'),
                 ...buildEnvVarFromOption(clerkJSVersion, 'PUBLIC_CLERK_JS_VERSION'),
                 ...buildEnvVarFromOption(prefetchUI === false ? 'false' : undefined, 'PUBLIC_CLERK_PREFETCH_UI'),
+                ...buildEnvVarFromOption(envPublishableKey, 'PUBLIC_CLERK_PUBLISHABLE_KEY'),
+                ...buildEnvVarFromOption(envSecretKey, 'CLERK_SECRET_KEY'),
+                // Keyless URLs are now handled by middleware, not vite.define
               },
 
               ssr: {
@@ -157,7 +167,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
 
 function createClerkEnvSchema() {
   return {
-    PUBLIC_CLERK_PUBLISHABLE_KEY: envField.string({ context: 'client', access: 'public' }),
+    PUBLIC_CLERK_PUBLISHABLE_KEY: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_SIGN_IN_URL: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_SIGN_UP_URL: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_IS_SATELLITE: envField.boolean({ context: 'client', access: 'public', optional: true }),
@@ -169,7 +179,9 @@ function createClerkEnvSchema() {
     PUBLIC_CLERK_UI_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
     PUBLIC_CLERK_TELEMETRY_DISABLED: envField.boolean({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_TELEMETRY_DEBUG: envField.boolean({ context: 'client', access: 'public', optional: true }),
-    CLERK_SECRET_KEY: envField.string({ context: 'server', access: 'secret' }),
+    // Note: KEYLESS_CLAIM_URL and KEYLESS_API_KEYS_URL are dynamically resolved by middleware, not user-configurable
+    PUBLIC_CLERK_KEYLESS_DISABLED: envField.boolean({ context: 'client', access: 'public', optional: true }),
+    CLERK_SECRET_KEY: envField.string({ context: 'server', access: 'secret', optional: true }),
     CLERK_MACHINE_SECRET_KEY: envField.string({ context: 'server', access: 'secret', optional: true }),
     CLERK_JWT_KEY: envField.string({ context: 'server', access: 'secret', optional: true }),
   };

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

@@ -54,12 +54,17 @@ async function createClerkInstanceInternal<TUi extends Ui = Ui>(options?: AstroC
     $clerk.set(clerkJSInstance);
   }
 
+  const keylessClaimUrl = (options as any)?.__internal_keylessClaimUrl;
+  const keylessApiKeysUrl = (options as any)?.__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()
     clerkUICtor,
+    ...(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

@@ -56,6 +56,10 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & { publish
       disabled: isTruthy(import.meta.env.PUBLIC_CLERK_TELEMETRY_DISABLED),
       debug: isTruthy(import.meta.env.PUBLIC_CLERK_TELEMETRY_DEBUG),
     },
+    // Read from params (server-injected via __CLERK_ASTRO_SAFE_VARS__)
+    // These are dynamically resolved by middleware, not from env vars
+    __internal_keylessClaimUrl: (params as any)?.keylessClaimUrl,
+    __internal_keylessApiKeysUrl: (params as any)?.keylessApiKeysUrl,
     ...rest,
   };
 };

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

@@ -24,10 +24,12 @@
 
 import { authAsyncStorage } from '#async-local-storage';
 
+import { canUseKeyless } from '../utils/feature-flags';
 import { buildClerkHotloadScript } from './build-clerk-hotload-script';
 import { clerkClient } from './clerk-client';
 import { createCurrentUser } from './current-user';
 import { getClientSafeEnv, getSafeEnv } from './get-safe-env';
+import { resolveKeysWithKeylessFallback } from './keyless/utils';
 import { serverRedirectWithAuth } from './server-redirect-with-auth';
 import type {
   AstroMiddleware,
@@ -79,9 +81,38 @@
 
     const clerkRequest = createClerkRequest(context.request);
 
+    // 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);
+
+        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 }),
+          };
+        }
+      } catch (error) {
+        // Silently fail - continue without keyless
+      }
+    }
+
     const requestState = await clerkClient(context).authenticateRequest(
       clerkRequest,
-      createAuthenticateRequestOptions(clerkRequest, options, context),
+      createAuthenticateRequestOptions(clerkRequest, keylessOptions, context),
     );
 
     const locationHeader = requestState.headers.get(constants.Headers.Location);
@@ -104,6 +135,16 @@
 
     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

@@ -21,11 +21,14 @@ 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),
-    pk: getContextEnvVar('PUBLIC_CLERK_PUBLISHABLE_KEY', context),
+    // Use keyless publishable key if available, otherwise read from env
+    pk: locals.keylessPublishableKey || 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),
@@ -38,6 +41,9 @@ 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,
   };
 }
 
@@ -49,12 +55,19 @@ function getSafeEnv(context: ContextOrLocals) {
  * This is a way to get around it.
  */
 function getClientSafeEnv(context: ContextOrLocals) {
+  const locals = ('locals' in context ? context.locals : context) as any;
+
   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,
   };
 }
 

packages/astro/src/server/keyless/file-storage.ts

@@ -0,0 +1,20 @@
+import type { KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+  cwd?: () => string;
+}
+
+export async function createFileStorage(options: FileStorageOptions = {}): Promise<KeylessStorage> {
+  const { cwd = () => process.cwd() } = options;
+
+  const [{ default: fs }, { default: path }] = await Promise.all([import('node:fs'), import('node:path')]);
+
+  const { createNodeFileStorage } = await import('@clerk/shared/keyless');
+
+  return createNodeFileStorage(fs, path, {
+    cwd,
+    frameworkPackageName: '@clerk/astro',
+  });
+}