feat(astro): Add support for keyless mode

.changeset/perfect-chicken-scream.md

@@ -0,0 +1,5 @@
+---
+"@clerk/astro": minor
+---
+
+Introduce Keyless quickstart for Astro. This allows the Clerk SDK to be used without having to sign up and paste your keys manually.

integration/tests/astro/keyless.test.ts

@@ -0,0 +1,54 @@
+import { test } from '@playwright/test';
+
+import type { Application } from '../../models/application';
+import { appConfigs } from '../../presets';
+import {
+  testClaimedAppWithMissingKeys,
+  testKeylessRemovedAfterEnvAndRestart,
+  testToggleCollapsePopoverAndClaim,
+} 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 }) => {
+    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 ({
+    page,
+    context,
+  }) => {
+    await testClaimedAppWithMissingKeys({ page, context, app, dashboardUrl });
+  });
+
+  test('Keyless popover is removed after adding keys to .env and restarting.', async ({ page, context }) => {
+    await testKeylessRemovedAfterEnvAndRestart({ page, context, app });
+  });
+});

packages/astro/package.json

@@ -97,7 +97,7 @@
   },
   "devDependencies": {
     "@clerk/ui": "workspace:^",
-    "astro": "^5.15.9"
+    "astro": "^5.17.1"
   },
   "peerDependencies": {
     "astro": "^4.15.0 || ^5.0.0"

packages/astro/src/env.d.ts

@@ -21,6 +21,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 {
@@ -30,6 +31,9 @@ interface ImportMeta {
 declare namespace App {
   interface Locals {
     runtime: { env: InternalEnv };
+    keylessClaimUrl?: string;
+    keylessApiKeysUrl?: string;
+    keylessPublishableKey?: string;
   }
 }
 

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

@@ -166,7 +166,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 }),
@@ -179,7 +179,20 @@ function createClerkEnvSchema() {
     PUBLIC_CLERK_PREFETCH_UI: envField.string({ context: 'client', access: 'public', optional: 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' }),
+    PUBLIC_CLERK_KEYLESS_CLAIM_URL: envField.string({
+      context: 'client',
+      access: 'public',
+      optional: true,
+      url: true,
+    }),
+    PUBLIC_CLERK_KEYLESS_API_KEYS_URL: envField.string({
+      context: 'client',
+      access: 'public',
+      optional: true,
+      url: true,
+    }),
+    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

@@ -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 } from '../types';
+import type { AstroClerkCreateInstanceParams, AstroClerkUpdateOptions, InternalRuntimeOptions } from '../types';
 import { invokeClerkAstroJSFunctions } from './invoke-clerk-astro-js-functions';
 import { mountAllClerkAstroJSComponents } from './mount-clerk-astro-js-components';
 import { runOnce } from './run-once';
@@ -54,12 +54,18 @@ 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,6 +1,6 @@
 import { isTruthy } from '@clerk/shared/underscore';
 
-import type { AstroClerkIntegrationParams } from '../types';
+import type { AstroClerkIntegrationParams, InternalRuntimeOptions } from '../types';
 
 /**
  * Merges `prefetchUI` param with env vars.
@@ -25,7 +25,7 @@ function mergePrefetchUIConfig(paramPrefetchUI: AstroClerkIntegrationParams['pre
 /**
  * @internal
  */
-const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & { publishableKey?: string }) => {
+const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & InternalRuntimeOptions) => {
   const {
     signInUrl: paramSignIn,
     signUpUrl: paramSignUp,
@@ -42,13 +42,17 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & { publish
     ...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,
-    publishableKey: paramPublishableKey || import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY || '',
+    // In keyless mode, use server-injected publishableKey from params
+    publishableKey:
+      paramPublishableKey || internalOptions?.publishableKey || import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY || '',
     clerkJSUrl: paramClerkJSUrl || import.meta.env.PUBLIC_CLERK_JS_URL,
     clerkJSVersion: paramClerkJSVersion || import.meta.env.PUBLIC_CLERK_JS_VERSION,
     clerkUIUrl: paramClerkUIUrl || import.meta.env.PUBLIC_CLERK_UI_URL,
@@ -58,6 +62,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: internalOptions?.keylessClaimUrl,
+    __internal_keylessApiKeysUrl: internalOptions?.keylessApiKeysUrl,
     ...rest,
   };
 };

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

@@ -24,10 +24,12 @@ import type { APIContext } from 'astro';
 
 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,
@@ -49,7 +51,7 @@ type ClerkAstroMiddlewareHandler = (
   next: AstroMiddlewareNextParam,
 ) => AstroMiddlewareReturn | undefined;
 
-type ClerkAstroMiddlewareOptions = AuthenticateRequestOptions;
+export type ClerkAstroMiddlewareOptions = AuthenticateRequestOptions;
 
 /**
  * Middleware for Astro that handles authentication and authorization with Clerk.
@@ -79,9 +81,42 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]): any => {
 
     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,
+          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 }),
+          };
+        }
+      } catch {
+        // 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 +139,16 @@ 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

@@ -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),
@@ -39,6 +42,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,
   };
 }
 
@@ -50,12 +56,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;
+
   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,29 @@
+import { createNodeFileStorage, type KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+  cwd?: () => string;
+}
+
+/**
+ * Creates a file-based storage adapter for keyless mode.
+ * Uses dynamic imports to avoid bundler issues with edge runtimes.
+ */
+export async function createFileStorage(options: FileStorageOptions = {}): Promise<KeylessStorage> {
+  const { cwd = () => process.cwd() } = options;
+
+  try {
+    const [fs, path] = await Promise.all([import('node:fs'), import('node:path')]);
+
+    return createNodeFileStorage(fs, path, {
+      cwd,
+      frameworkPackageName: '@clerk/astro',
+    });
+  } catch {
+    throw new Error(
+      'Keyless mode requires a Node.js runtime with file system access. ' +
+        'Set PUBLIC_CLERK_KEYLESS_DISABLED=1 or CLERK_KEYLESS_DISABLED=1 to disable keyless mode.',
+    );
+  }
+}