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

@@ -136,7 +136,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 }),
@@ -149,7 +149,8 @@ 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_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,19 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { createNodeFileStorage, type KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+ cwd?: () => string;
+}
+
+export function createFileStorage(options: FileStorageOptions = {}): KeylessStorage {
+ const { cwd = () => process.cwd() } = options;
+
+ return createNodeFileStorage(fs, path, {
+ cwd,
+ frameworkPackageName: '@clerk/astro',
+ });
+}

.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

@@ -136,7 +136,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 }),
@@ -149,7 +149,8 @@ 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_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,19 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { createNodeFileStorage, type KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+ cwd?: () => string;
+}
+
+export function createFileStorage(options: FileStorageOptions = {}): KeylessStorage {
+ const { cwd = () => process.cwd() } = options;
+
+ return createNodeFileStorage(fs, path, {
+ cwd,
+ frameworkPackageName: '@clerk/astro',
+ });
+}

.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

@@ -136,7 +136,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 }),
@@ -149,7 +149,8 @@ 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_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,19 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { createNodeFileStorage, type KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+ cwd?: () => string;
+}
+
+export function createFileStorage(options: FileStorageOptions = {}): KeylessStorage {
+ const { cwd = () => process.cwd() } = options;
+
+ return createNodeFileStorage(fs, path, {
+ cwd,
+ frameworkPackageName: '@clerk/astro',
+ });
+}

.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

@@ -136,7 +136,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 }),
@@ -149,7 +149,8 @@ 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_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,19 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { createNodeFileStorage, type KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+ cwd?: () => string;
+}
+
+export function createFileStorage(options: FileStorageOptions = {}): KeylessStorage {
+ const { cwd = () => process.cwd() } = options;
+
+ return createNodeFileStorage(fs, path, {
+ cwd,
+ frameworkPackageName: '@clerk/astro',
+ });
+}

.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

@@ -136,7 +136,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 }),
@@ -149,7 +149,8 @@ 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_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,19 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { createNodeFileStorage, type KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+ cwd?: () => string;
+}
+
+export function createFileStorage(options: FileStorageOptions = {}): KeylessStorage {
+ const { cwd = () => process.cwd() } = options;
+
+ return createNodeFileStorage(fs, path, {
+ cwd,
+ frameworkPackageName: '@clerk/astro',
+ });
+}

.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

@@ -136,7 +136,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 }),
@@ -149,7 +149,8 @@ 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_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,19 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { createNodeFileStorage, type KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+ cwd?: () => string;
+}
+
+export function createFileStorage(options: FileStorageOptions = {}): KeylessStorage {
+ const { cwd = () => process.cwd() } = options;
+
+ return createNodeFileStorage(fs, path, {
+ cwd,
+ frameworkPackageName: '@clerk/astro',
+ });
+}

.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

@@ -136,7 +136,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 }),
@@ -149,7 +149,8 @@ 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_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,19 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { createNodeFileStorage, type KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+ cwd?: () => string;
+}
+
+export function createFileStorage(options: FileStorageOptions = {}): KeylessStorage {
+ const { cwd = () => process.cwd() } = options;
+
+ return createNodeFileStorage(fs, path, {
+ cwd,
+ frameworkPackageName: '@clerk/astro',
+ });
+}

.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

@@ -136,7 +136,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 }),
@@ -149,7 +149,8 @@ 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_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,19 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { createNodeFileStorage, type KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+ cwd?: () => string;
+}
+
+export function createFileStorage(options: FileStorageOptions = {}): KeylessStorage {
+ const { cwd = () => process.cwd() } = options;
+
+ return createNodeFileStorage(fs, path, {
+ cwd,
+ frameworkPackageName: '@clerk/astro',
+ });
+}