feat(nextjs): Mark keyless onboarding as complete when stored keys match explicit keys

.changeset/fuzzy-ghosts-kneel.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Mark keyless onboarding as complete when stored keys match explicit keys

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

@@ -1,3 +1,4 @@
+import { joinPaths } from '../../util/path';
 import type { AccountlessApplication } from '../resources/AccountlessApplication';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,4 +11,11 @@ export class AccountlessApplicationAPI extends AbstractAPI {
  path: basePath,
  });
  }
+
+ public async completeAccountlessApplicationOnboarding() {
+ return this.request<AccountlessApplication>({
+ method: 'POST',
+ path: joinPaths(basePath, 'complete'),
+ });
+ }
 }

packages/clerk-js/src/ui/components/KeylessPrompt/index.tsx

@@ -15,7 +15,7 @@ import { useRevalidateEnvironment } from './use-revalidate-environment';
 type KeylessPromptProps = {
  claimUrl: string;
  copyKeysUrl: string;
- onDismiss: (() => Promise<unknown>) | undefined;
+ onDismiss: (() => Promise<unknown>) | undefined | null;
 };
 
 const buttonIdentifierPrefix = `--clerk-keyless-prompt`;

packages/nextjs/src/app-router/keyless-actions.ts

@@ -43,12 +43,12 @@ export async function createOrReadKeylessAction(): Promise<null | Omit<Accountle
  return null;
  }
 
- const { keylessLogger, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
+ const { clerkDevelopmentCache, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
 
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: result.publishableKey,
  msg: createKeylessModeMessage(result),
  });

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 
 import { PromisifiedAuthProvider } from '../../client-boundary/PromisifiedAuthProvider';
 import { getDynamicAuthData } from '../../server/buildClerkProps';
+import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -96,7 +97,7 @@ export async function ClerkProvider(
  const newOrReadKeys = await import('../../server/keyless-node.js')
  .then(mod => mod.createOrReadKeyless())
  .catch(() => null);
- const { keylessLogger, createConfirmationMessage, createKeylessModeMessage } = await import(
+ const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
  '../../server/keyless-log-cache.js'
  );
 
@@ -108,7 +109,8 @@ export async function ClerkProvider(
  publishableKey: newOrReadKeys.publishableKey,
  __internal_keyless_claimKeylessApplicationUrl: newOrReadKeys.claimUrl,
  __internal_keyless_copyInstanceKeysUrl: newOrReadKeys.apiKeysUrl,
- __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : undefined,
+ // Explicitly use `null` instead of `undefined` here to avoid persisting `deleteKeylessAction` during merging of options.
+ __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : null,
  })}
  nonce={await generateNonce()}
  initialState={await generateStatePromise()}
@@ -118,10 +120,37 @@ export async function ClerkProvider(
  );
 
  if (runningWithClaimedKeys) {
+ try {
+ const secretKey = await import('../../server/keyless-node.js').then(
+ mod => mod.safeParseClerkFile()?.secretKey,
+ );
+ if (!secretKey) {
+ // we will ignore it later
+ throw new Error(secretKey);
+ }
+ const client = createClerkClientWithOptions({
+ secretKey,
+ });
+
+ /**
+ * Notifying the dashboard the should runs once. We are controlling this behaviour by caching the result of the request.
+ * If the request fails, it will be considered stale after 10 minutes, otherwise it is cached for 24 hours.
+ */
+ await clerkDevelopmentCache?.run(
+ () => client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding(),
+ {
+ cacheKey: `${newOrReadKeys.publishableKey}_complete`,
+ onSuccessStale: 24 * 60 * 60 * 1000, // 24 hours
+ },
+ );
+ } catch {
+ // ignore
+ }
+
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: `${newOrReadKeys.publishableKey}_claimed`,
  msg: createConfirmationMessage(),
  });
@@ -145,7 +174,7 @@ export async function ClerkProvider(
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: newOrReadKeys.publishableKey,
  msg: createKeylessModeMessage({ ...newOrReadKeys, claimUrl: claimUrl.href }),
  });

packages/nextjs/src/global.d.ts

@@ -44,8 +44,20 @@ declare namespace globalThis {
  // eslint-disable-next-line no-var
  var __clerk_internal_keyless_logger:
  | {
- __cache: Map<string, { expiresAt: number }>;
+ __cache: Map<string, { expiresAt: number; data?: unknown }>;
  log: (param: { cacheKey: string; msg: string }) => void;
+ run: (
+ callback: () => Promise<unknown>,
+ {
+ cacheKey,
+ onSuccessStale,
+ onErrorStale,
+ }: {
+ cacheKey: string;
+ onSuccessStale?: number;
+ onErrorStale?: number;
+ },
+ ) => Promise<unknown>;
  }
  | undefined;
 }

packages/nextjs/src/server/keyless-log-cache.ts

@@ -3,16 +3,16 @@ import { isDevelopmentEnvironment } from '@clerk/shared/utils';
 // 10 minutes in milliseconds
 const THROTTLE_DURATION_MS = 10 * 60 * 1000;
 
-function createClerkDevLogger() {
+function createClerkDevCache() {
  if (!isDevelopmentEnvironment()) {
  return;
  }
 
  if (!global.__clerk_internal_keyless_logger) {
  global.__clerk_internal_keyless_logger = {
- __cache: new Map<string, { expiresAt: number }>(),
+ __cache: new Map<string, { expiresAt: number; data?: unknown }>(),
 
- log: function ({ cacheKey, msg }: { cacheKey: string; msg: string }) {
+ log: function ({ cacheKey, msg }) {
  if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
  return;
  }
@@ -23,6 +23,30 @@ function createClerkDevLogger() {
  expiresAt: Date.now() + THROTTLE_DURATION_MS,
  });
  },
+ run: async function (
+ callback,
+ { cacheKey, onSuccessStale = THROTTLE_DURATION_MS, onErrorStale = THROTTLE_DURATION_MS },
+ ) {
+ if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
+ return this.__cache.get(cacheKey)?.data;
+ }
+
+ try {
+ const result = await callback();
+
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onSuccessStale,
+ data: result,
+ });
+ return result;
+ } catch (e) {
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onErrorStale,
+ });
+
+ throw e;
+ }
+ },
  };
  }
 
@@ -37,4 +61,4 @@ export const createConfirmationMessage = () => {
  return `\n\x1b[35m\n[Clerk]:\x1b[0m Your application is running with your claimed keys.\nYou can safely remove the \x1b[35m.clerk/\x1b[0m from your project.\n`;
 };
 
-export const keylessLogger = createClerkDevLogger();
+export const clerkDevelopmentCache = createClerkDevCache();

packages/types/src/clerk.ts

@@ -780,7 +780,7 @@ export type ClerkOptions = ClerkOptionsNavigation &
  * Pass a function that will trigger the unmounting of the Keyless Prompt.
  * It should cause the values of `__internal_claimKeylessApplicationUrl` and `__internal_copyInstanceKeysUrl` to become undefined.
  */
- __internal_keyless_dismissPrompt?: () => Promise<void>;
+ __internal_keyless_dismissPrompt?: (() => Promise<void>) | null;
  };
 
 export interface NavigateOptions {

.changeset/fuzzy-ghosts-kneel.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Mark keyless onboarding as complete when stored keys match explicit keys

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

@@ -1,3 +1,4 @@
+import { joinPaths } from '../../util/path';
 import type { AccountlessApplication } from '../resources/AccountlessApplication';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,4 +11,11 @@ export class AccountlessApplicationAPI extends AbstractAPI {
  path: basePath,
  });
  }
+
+ public async completeAccountlessApplicationOnboarding() {
+ return this.request<AccountlessApplication>({
+ method: 'POST',
+ path: joinPaths(basePath, 'complete'),
+ });
+ }
 }

packages/clerk-js/src/ui/components/KeylessPrompt/index.tsx

@@ -15,7 +15,7 @@ import { useRevalidateEnvironment } from './use-revalidate-environment';
 type KeylessPromptProps = {
  claimUrl: string;
  copyKeysUrl: string;
- onDismiss: (() => Promise<unknown>) | undefined;
+ onDismiss: (() => Promise<unknown>) | undefined | null;
 };
 
 const buttonIdentifierPrefix = `--clerk-keyless-prompt`;

packages/nextjs/src/app-router/keyless-actions.ts

@@ -43,12 +43,12 @@ export async function createOrReadKeylessAction(): Promise<null | Omit<Accountle
  return null;
  }
 
- const { keylessLogger, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
+ const { clerkDevelopmentCache, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
 
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: result.publishableKey,
  msg: createKeylessModeMessage(result),
  });

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 
 import { PromisifiedAuthProvider } from '../../client-boundary/PromisifiedAuthProvider';
 import { getDynamicAuthData } from '../../server/buildClerkProps';
+import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -96,7 +97,7 @@ export async function ClerkProvider(
  const newOrReadKeys = await import('../../server/keyless-node.js')
  .then(mod => mod.createOrReadKeyless())
  .catch(() => null);
- const { keylessLogger, createConfirmationMessage, createKeylessModeMessage } = await import(
+ const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
  '../../server/keyless-log-cache.js'
  );
 
@@ -108,7 +109,8 @@ export async function ClerkProvider(
  publishableKey: newOrReadKeys.publishableKey,
  __internal_keyless_claimKeylessApplicationUrl: newOrReadKeys.claimUrl,
  __internal_keyless_copyInstanceKeysUrl: newOrReadKeys.apiKeysUrl,
- __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : undefined,
+ // Explicitly use `null` instead of `undefined` here to avoid persisting `deleteKeylessAction` during merging of options.
+ __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : null,
  })}
  nonce={await generateNonce()}
  initialState={await generateStatePromise()}
@@ -118,10 +120,37 @@ export async function ClerkProvider(
  );
 
  if (runningWithClaimedKeys) {
+ try {
+ const secretKey = await import('../../server/keyless-node.js').then(
+ mod => mod.safeParseClerkFile()?.secretKey,
+ );
+ if (!secretKey) {
+ // we will ignore it later
+ throw new Error(secretKey);
+ }
+ const client = createClerkClientWithOptions({
+ secretKey,
+ });
+
+ /**
+ * Notifying the dashboard the should runs once. We are controlling this behaviour by caching the result of the request.
+ * If the request fails, it will be considered stale after 10 minutes, otherwise it is cached for 24 hours.
+ */
+ await clerkDevelopmentCache?.run(
+ () => client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding(),
+ {
+ cacheKey: `${newOrReadKeys.publishableKey}_complete`,
+ onSuccessStale: 24 * 60 * 60 * 1000, // 24 hours
+ },
+ );
+ } catch {
+ // ignore
+ }
+
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: `${newOrReadKeys.publishableKey}_claimed`,
  msg: createConfirmationMessage(),
  });
@@ -145,7 +174,7 @@ export async function ClerkProvider(
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: newOrReadKeys.publishableKey,
  msg: createKeylessModeMessage({ ...newOrReadKeys, claimUrl: claimUrl.href }),
  });

packages/nextjs/src/global.d.ts

@@ -44,8 +44,20 @@ declare namespace globalThis {
  // eslint-disable-next-line no-var
  var __clerk_internal_keyless_logger:
  | {
- __cache: Map<string, { expiresAt: number }>;
+ __cache: Map<string, { expiresAt: number; data?: unknown }>;
  log: (param: { cacheKey: string; msg: string }) => void;
+ run: (
+ callback: () => Promise<unknown>,
+ {
+ cacheKey,
+ onSuccessStale,
+ onErrorStale,
+ }: {
+ cacheKey: string;
+ onSuccessStale?: number;
+ onErrorStale?: number;
+ },
+ ) => Promise<unknown>;
  }
  | undefined;
 }

packages/nextjs/src/server/keyless-log-cache.ts

@@ -3,16 +3,16 @@ import { isDevelopmentEnvironment } from '@clerk/shared/utils';
 // 10 minutes in milliseconds
 const THROTTLE_DURATION_MS = 10 * 60 * 1000;
 
-function createClerkDevLogger() {
+function createClerkDevCache() {
  if (!isDevelopmentEnvironment()) {
  return;
  }
 
  if (!global.__clerk_internal_keyless_logger) {
  global.__clerk_internal_keyless_logger = {
- __cache: new Map<string, { expiresAt: number }>(),
+ __cache: new Map<string, { expiresAt: number; data?: unknown }>(),
 
- log: function ({ cacheKey, msg }: { cacheKey: string; msg: string }) {
+ log: function ({ cacheKey, msg }) {
  if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
  return;
  }
@@ -23,6 +23,30 @@ function createClerkDevLogger() {
  expiresAt: Date.now() + THROTTLE_DURATION_MS,
  });
  },
+ run: async function (
+ callback,
+ { cacheKey, onSuccessStale = THROTTLE_DURATION_MS, onErrorStale = THROTTLE_DURATION_MS },
+ ) {
+ if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
+ return this.__cache.get(cacheKey)?.data;
+ }
+
+ try {
+ const result = await callback();
+
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onSuccessStale,
+ data: result,
+ });
+ return result;
+ } catch (e) {
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onErrorStale,
+ });
+
+ throw e;
+ }
+ },
  };
  }
 
@@ -37,4 +61,4 @@ export const createConfirmationMessage = () => {
  return `\n\x1b[35m\n[Clerk]:\x1b[0m Your application is running with your claimed keys.\nYou can safely remove the \x1b[35m.clerk/\x1b[0m from your project.\n`;
 };
 
-export const keylessLogger = createClerkDevLogger();
+export const clerkDevelopmentCache = createClerkDevCache();

packages/types/src/clerk.ts

@@ -780,7 +780,7 @@ export type ClerkOptions = ClerkOptionsNavigation &
  * Pass a function that will trigger the unmounting of the Keyless Prompt.
  * It should cause the values of `__internal_claimKeylessApplicationUrl` and `__internal_copyInstanceKeysUrl` to become undefined.
  */
- __internal_keyless_dismissPrompt?: () => Promise<void>;
+ __internal_keyless_dismissPrompt?: (() => Promise<void>) | null;
  };
 
 export interface NavigateOptions {

.changeset/fuzzy-ghosts-kneel.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Mark keyless onboarding as complete when stored keys match explicit keys

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

@@ -1,3 +1,4 @@
+import { joinPaths } from '../../util/path';
 import type { AccountlessApplication } from '../resources/AccountlessApplication';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,4 +11,11 @@ export class AccountlessApplicationAPI extends AbstractAPI {
  path: basePath,
  });
  }
+
+ public async completeAccountlessApplicationOnboarding() {
+ return this.request<AccountlessApplication>({
+ method: 'POST',
+ path: joinPaths(basePath, 'complete'),
+ });
+ }
 }

packages/clerk-js/src/ui/components/KeylessPrompt/index.tsx

@@ -15,7 +15,7 @@ import { useRevalidateEnvironment } from './use-revalidate-environment';
 type KeylessPromptProps = {
  claimUrl: string;
  copyKeysUrl: string;
- onDismiss: (() => Promise<unknown>) | undefined;
+ onDismiss: (() => Promise<unknown>) | undefined | null;
 };
 
 const buttonIdentifierPrefix = `--clerk-keyless-prompt`;

packages/nextjs/src/app-router/keyless-actions.ts

@@ -43,12 +43,12 @@ export async function createOrReadKeylessAction(): Promise<null | Omit<Accountle
  return null;
  }
 
- const { keylessLogger, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
+ const { clerkDevelopmentCache, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
 
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: result.publishableKey,
  msg: createKeylessModeMessage(result),
  });

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 
 import { PromisifiedAuthProvider } from '../../client-boundary/PromisifiedAuthProvider';
 import { getDynamicAuthData } from '../../server/buildClerkProps';
+import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -96,7 +97,7 @@ export async function ClerkProvider(
  const newOrReadKeys = await import('../../server/keyless-node.js')
  .then(mod => mod.createOrReadKeyless())
  .catch(() => null);
- const { keylessLogger, createConfirmationMessage, createKeylessModeMessage } = await import(
+ const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
  '../../server/keyless-log-cache.js'
  );
 
@@ -108,7 +109,8 @@ export async function ClerkProvider(
  publishableKey: newOrReadKeys.publishableKey,
  __internal_keyless_claimKeylessApplicationUrl: newOrReadKeys.claimUrl,
  __internal_keyless_copyInstanceKeysUrl: newOrReadKeys.apiKeysUrl,
- __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : undefined,
+ // Explicitly use `null` instead of `undefined` here to avoid persisting `deleteKeylessAction` during merging of options.
+ __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : null,
  })}
  nonce={await generateNonce()}
  initialState={await generateStatePromise()}
@@ -118,10 +120,37 @@ export async function ClerkProvider(
  );
 
  if (runningWithClaimedKeys) {
+ try {
+ const secretKey = await import('../../server/keyless-node.js').then(
+ mod => mod.safeParseClerkFile()?.secretKey,
+ );
+ if (!secretKey) {
+ // we will ignore it later
+ throw new Error(secretKey);
+ }
+ const client = createClerkClientWithOptions({
+ secretKey,
+ });
+
+ /**
+ * Notifying the dashboard the should runs once. We are controlling this behaviour by caching the result of the request.
+ * If the request fails, it will be considered stale after 10 minutes, otherwise it is cached for 24 hours.
+ */
+ await clerkDevelopmentCache?.run(
+ () => client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding(),
+ {
+ cacheKey: `${newOrReadKeys.publishableKey}_complete`,
+ onSuccessStale: 24 * 60 * 60 * 1000, // 24 hours
+ },
+ );
+ } catch {
+ // ignore
+ }
+
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: `${newOrReadKeys.publishableKey}_claimed`,
  msg: createConfirmationMessage(),
  });
@@ -145,7 +174,7 @@ export async function ClerkProvider(
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: newOrReadKeys.publishableKey,
  msg: createKeylessModeMessage({ ...newOrReadKeys, claimUrl: claimUrl.href }),
  });

packages/nextjs/src/global.d.ts

@@ -44,8 +44,20 @@ declare namespace globalThis {
  // eslint-disable-next-line no-var
  var __clerk_internal_keyless_logger:
  | {
- __cache: Map<string, { expiresAt: number }>;
+ __cache: Map<string, { expiresAt: number; data?: unknown }>;
  log: (param: { cacheKey: string; msg: string }) => void;
+ run: (
+ callback: () => Promise<unknown>,
+ {
+ cacheKey,
+ onSuccessStale,
+ onErrorStale,
+ }: {
+ cacheKey: string;
+ onSuccessStale?: number;
+ onErrorStale?: number;
+ },
+ ) => Promise<unknown>;
  }
  | undefined;
 }

packages/nextjs/src/server/keyless-log-cache.ts

@@ -3,16 +3,16 @@ import { isDevelopmentEnvironment } from '@clerk/shared/utils';
 // 10 minutes in milliseconds
 const THROTTLE_DURATION_MS = 10 * 60 * 1000;
 
-function createClerkDevLogger() {
+function createClerkDevCache() {
  if (!isDevelopmentEnvironment()) {
  return;
  }
 
  if (!global.__clerk_internal_keyless_logger) {
  global.__clerk_internal_keyless_logger = {
- __cache: new Map<string, { expiresAt: number }>(),
+ __cache: new Map<string, { expiresAt: number; data?: unknown }>(),
 
- log: function ({ cacheKey, msg }: { cacheKey: string; msg: string }) {
+ log: function ({ cacheKey, msg }) {
  if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
  return;
  }
@@ -23,6 +23,30 @@ function createClerkDevLogger() {
  expiresAt: Date.now() + THROTTLE_DURATION_MS,
  });
  },
+ run: async function (
+ callback,
+ { cacheKey, onSuccessStale = THROTTLE_DURATION_MS, onErrorStale = THROTTLE_DURATION_MS },
+ ) {
+ if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
+ return this.__cache.get(cacheKey)?.data;
+ }
+
+ try {
+ const result = await callback();
+
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onSuccessStale,
+ data: result,
+ });
+ return result;
+ } catch (e) {
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onErrorStale,
+ });
+
+ throw e;
+ }
+ },
  };
  }
 
@@ -37,4 +61,4 @@ export const createConfirmationMessage = () => {
  return `\n\x1b[35m\n[Clerk]:\x1b[0m Your application is running with your claimed keys.\nYou can safely remove the \x1b[35m.clerk/\x1b[0m from your project.\n`;
 };
 
-export const keylessLogger = createClerkDevLogger();
+export const clerkDevelopmentCache = createClerkDevCache();

packages/types/src/clerk.ts

@@ -780,7 +780,7 @@ export type ClerkOptions = ClerkOptionsNavigation &
  * Pass a function that will trigger the unmounting of the Keyless Prompt.
  * It should cause the values of `__internal_claimKeylessApplicationUrl` and `__internal_copyInstanceKeysUrl` to become undefined.
  */
- __internal_keyless_dismissPrompt?: () => Promise<void>;
+ __internal_keyless_dismissPrompt?: (() => Promise<void>) | null;
  };
 
 export interface NavigateOptions {

.changeset/fuzzy-ghosts-kneel.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Mark keyless onboarding as complete when stored keys match explicit keys

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

@@ -1,3 +1,4 @@
+import { joinPaths } from '../../util/path';
 import type { AccountlessApplication } from '../resources/AccountlessApplication';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,4 +11,11 @@ export class AccountlessApplicationAPI extends AbstractAPI {
  path: basePath,
  });
  }
+
+ public async completeAccountlessApplicationOnboarding() {
+ return this.request<AccountlessApplication>({
+ method: 'POST',
+ path: joinPaths(basePath, 'complete'),
+ });
+ }
 }

packages/clerk-js/src/ui/components/KeylessPrompt/index.tsx

@@ -15,7 +15,7 @@ import { useRevalidateEnvironment } from './use-revalidate-environment';
 type KeylessPromptProps = {
  claimUrl: string;
  copyKeysUrl: string;
- onDismiss: (() => Promise<unknown>) | undefined;
+ onDismiss: (() => Promise<unknown>) | undefined | null;
 };
 
 const buttonIdentifierPrefix = `--clerk-keyless-prompt`;

packages/nextjs/src/app-router/keyless-actions.ts

@@ -43,12 +43,12 @@ export async function createOrReadKeylessAction(): Promise<null | Omit<Accountle
  return null;
  }
 
- const { keylessLogger, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
+ const { clerkDevelopmentCache, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
 
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: result.publishableKey,
  msg: createKeylessModeMessage(result),
  });

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 
 import { PromisifiedAuthProvider } from '../../client-boundary/PromisifiedAuthProvider';
 import { getDynamicAuthData } from '../../server/buildClerkProps';
+import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -96,7 +97,7 @@ export async function ClerkProvider(
  const newOrReadKeys = await import('../../server/keyless-node.js')
  .then(mod => mod.createOrReadKeyless())
  .catch(() => null);
- const { keylessLogger, createConfirmationMessage, createKeylessModeMessage } = await import(
+ const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
  '../../server/keyless-log-cache.js'
  );
 
@@ -108,7 +109,8 @@ export async function ClerkProvider(
  publishableKey: newOrReadKeys.publishableKey,
  __internal_keyless_claimKeylessApplicationUrl: newOrReadKeys.claimUrl,
  __internal_keyless_copyInstanceKeysUrl: newOrReadKeys.apiKeysUrl,
- __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : undefined,
+ // Explicitly use `null` instead of `undefined` here to avoid persisting `deleteKeylessAction` during merging of options.
+ __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : null,
  })}
  nonce={await generateNonce()}
  initialState={await generateStatePromise()}
@@ -118,10 +120,37 @@ export async function ClerkProvider(
  );
 
  if (runningWithClaimedKeys) {
+ try {
+ const secretKey = await import('../../server/keyless-node.js').then(
+ mod => mod.safeParseClerkFile()?.secretKey,
+ );
+ if (!secretKey) {
+ // we will ignore it later
+ throw new Error(secretKey);
+ }
+ const client = createClerkClientWithOptions({
+ secretKey,
+ });
+
+ /**
+ * Notifying the dashboard the should runs once. We are controlling this behaviour by caching the result of the request.
+ * If the request fails, it will be considered stale after 10 minutes, otherwise it is cached for 24 hours.
+ */
+ await clerkDevelopmentCache?.run(
+ () => client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding(),
+ {
+ cacheKey: `${newOrReadKeys.publishableKey}_complete`,
+ onSuccessStale: 24 * 60 * 60 * 1000, // 24 hours
+ },
+ );
+ } catch {
+ // ignore
+ }
+
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: `${newOrReadKeys.publishableKey}_claimed`,
  msg: createConfirmationMessage(),
  });
@@ -145,7 +174,7 @@ export async function ClerkProvider(
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: newOrReadKeys.publishableKey,
  msg: createKeylessModeMessage({ ...newOrReadKeys, claimUrl: claimUrl.href }),
  });

packages/nextjs/src/global.d.ts

@@ -44,8 +44,20 @@ declare namespace globalThis {
  // eslint-disable-next-line no-var
  var __clerk_internal_keyless_logger:
  | {
- __cache: Map<string, { expiresAt: number }>;
+ __cache: Map<string, { expiresAt: number; data?: unknown }>;
  log: (param: { cacheKey: string; msg: string }) => void;
+ run: (
+ callback: () => Promise<unknown>,
+ {
+ cacheKey,
+ onSuccessStale,
+ onErrorStale,
+ }: {
+ cacheKey: string;
+ onSuccessStale?: number;
+ onErrorStale?: number;
+ },
+ ) => Promise<unknown>;
  }
  | undefined;
 }

packages/nextjs/src/server/keyless-log-cache.ts

@@ -3,16 +3,16 @@ import { isDevelopmentEnvironment } from '@clerk/shared/utils';
 // 10 minutes in milliseconds
 const THROTTLE_DURATION_MS = 10 * 60 * 1000;
 
-function createClerkDevLogger() {
+function createClerkDevCache() {
  if (!isDevelopmentEnvironment()) {
  return;
  }
 
  if (!global.__clerk_internal_keyless_logger) {
  global.__clerk_internal_keyless_logger = {
- __cache: new Map<string, { expiresAt: number }>(),
+ __cache: new Map<string, { expiresAt: number; data?: unknown }>(),
 
- log: function ({ cacheKey, msg }: { cacheKey: string; msg: string }) {
+ log: function ({ cacheKey, msg }) {
  if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
  return;
  }
@@ -23,6 +23,30 @@ function createClerkDevLogger() {
  expiresAt: Date.now() + THROTTLE_DURATION_MS,
  });
  },
+ run: async function (
+ callback,
+ { cacheKey, onSuccessStale = THROTTLE_DURATION_MS, onErrorStale = THROTTLE_DURATION_MS },
+ ) {
+ if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
+ return this.__cache.get(cacheKey)?.data;
+ }
+
+ try {
+ const result = await callback();
+
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onSuccessStale,
+ data: result,
+ });
+ return result;
+ } catch (e) {
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onErrorStale,
+ });
+
+ throw e;
+ }
+ },
  };
  }
 
@@ -37,4 +61,4 @@ export const createConfirmationMessage = () => {
  return `\n\x1b[35m\n[Clerk]:\x1b[0m Your application is running with your claimed keys.\nYou can safely remove the \x1b[35m.clerk/\x1b[0m from your project.\n`;
 };
 
-export const keylessLogger = createClerkDevLogger();
+export const clerkDevelopmentCache = createClerkDevCache();

packages/types/src/clerk.ts

@@ -780,7 +780,7 @@ export type ClerkOptions = ClerkOptionsNavigation &
  * Pass a function that will trigger the unmounting of the Keyless Prompt.
  * It should cause the values of `__internal_claimKeylessApplicationUrl` and `__internal_copyInstanceKeysUrl` to become undefined.
  */
- __internal_keyless_dismissPrompt?: () => Promise<void>;
+ __internal_keyless_dismissPrompt?: (() => Promise<void>) | null;
  };
 
 export interface NavigateOptions {

.changeset/fuzzy-ghosts-kneel.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Mark keyless onboarding as complete when stored keys match explicit keys

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

@@ -1,3 +1,4 @@
+import { joinPaths } from '../../util/path';
 import type { AccountlessApplication } from '../resources/AccountlessApplication';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,4 +11,11 @@ export class AccountlessApplicationAPI extends AbstractAPI {
  path: basePath,
  });
  }
+
+ public async completeAccountlessApplicationOnboarding() {
+ return this.request<AccountlessApplication>({
+ method: 'POST',
+ path: joinPaths(basePath, 'complete'),
+ });
+ }
 }

packages/clerk-js/src/ui/components/KeylessPrompt/index.tsx

@@ -15,7 +15,7 @@ import { useRevalidateEnvironment } from './use-revalidate-environment';
 type KeylessPromptProps = {
  claimUrl: string;
  copyKeysUrl: string;
- onDismiss: (() => Promise<unknown>) | undefined;
+ onDismiss: (() => Promise<unknown>) | undefined | null;
 };
 
 const buttonIdentifierPrefix = `--clerk-keyless-prompt`;

packages/nextjs/src/app-router/keyless-actions.ts

@@ -43,12 +43,12 @@ export async function createOrReadKeylessAction(): Promise<null | Omit<Accountle
  return null;
  }
 
- const { keylessLogger, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
+ const { clerkDevelopmentCache, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
 
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: result.publishableKey,
  msg: createKeylessModeMessage(result),
  });

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 
 import { PromisifiedAuthProvider } from '../../client-boundary/PromisifiedAuthProvider';
 import { getDynamicAuthData } from '../../server/buildClerkProps';
+import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -96,7 +97,7 @@ export async function ClerkProvider(
  const newOrReadKeys = await import('../../server/keyless-node.js')
  .then(mod => mod.createOrReadKeyless())
  .catch(() => null);
- const { keylessLogger, createConfirmationMessage, createKeylessModeMessage } = await import(
+ const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
  '../../server/keyless-log-cache.js'
  );
 
@@ -108,7 +109,8 @@ export async function ClerkProvider(
  publishableKey: newOrReadKeys.publishableKey,
  __internal_keyless_claimKeylessApplicationUrl: newOrReadKeys.claimUrl,
  __internal_keyless_copyInstanceKeysUrl: newOrReadKeys.apiKeysUrl,
- __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : undefined,
+ // Explicitly use `null` instead of `undefined` here to avoid persisting `deleteKeylessAction` during merging of options.
+ __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : null,
  })}
  nonce={await generateNonce()}
  initialState={await generateStatePromise()}
@@ -118,10 +120,37 @@ export async function ClerkProvider(
  );
 
  if (runningWithClaimedKeys) {
+ try {
+ const secretKey = await import('../../server/keyless-node.js').then(
+ mod => mod.safeParseClerkFile()?.secretKey,
+ );
+ if (!secretKey) {
+ // we will ignore it later
+ throw new Error(secretKey);
+ }
+ const client = createClerkClientWithOptions({
+ secretKey,
+ });
+
+ /**
+ * Notifying the dashboard the should runs once. We are controlling this behaviour by caching the result of the request.
+ * If the request fails, it will be considered stale after 10 minutes, otherwise it is cached for 24 hours.
+ */
+ await clerkDevelopmentCache?.run(
+ () => client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding(),
+ {
+ cacheKey: `${newOrReadKeys.publishableKey}_complete`,
+ onSuccessStale: 24 * 60 * 60 * 1000, // 24 hours
+ },
+ );
+ } catch {
+ // ignore
+ }
+
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: `${newOrReadKeys.publishableKey}_claimed`,
  msg: createConfirmationMessage(),
  });
@@ -145,7 +174,7 @@ export async function ClerkProvider(
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: newOrReadKeys.publishableKey,
  msg: createKeylessModeMessage({ ...newOrReadKeys, claimUrl: claimUrl.href }),
  });

packages/nextjs/src/global.d.ts

@@ -44,8 +44,20 @@ declare namespace globalThis {
  // eslint-disable-next-line no-var
  var __clerk_internal_keyless_logger:
  | {
- __cache: Map<string, { expiresAt: number }>;
+ __cache: Map<string, { expiresAt: number; data?: unknown }>;
  log: (param: { cacheKey: string; msg: string }) => void;
+ run: (
+ callback: () => Promise<unknown>,
+ {
+ cacheKey,
+ onSuccessStale,
+ onErrorStale,
+ }: {
+ cacheKey: string;
+ onSuccessStale?: number;
+ onErrorStale?: number;
+ },
+ ) => Promise<unknown>;
  }
  | undefined;
 }

packages/nextjs/src/server/keyless-log-cache.ts

@@ -3,16 +3,16 @@ import { isDevelopmentEnvironment } from '@clerk/shared/utils';
 // 10 minutes in milliseconds
 const THROTTLE_DURATION_MS = 10 * 60 * 1000;
 
-function createClerkDevLogger() {
+function createClerkDevCache() {
  if (!isDevelopmentEnvironment()) {
  return;
  }
 
  if (!global.__clerk_internal_keyless_logger) {
  global.__clerk_internal_keyless_logger = {
- __cache: new Map<string, { expiresAt: number }>(),
+ __cache: new Map<string, { expiresAt: number; data?: unknown }>(),
 
- log: function ({ cacheKey, msg }: { cacheKey: string; msg: string }) {
+ log: function ({ cacheKey, msg }) {
  if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
  return;
  }
@@ -23,6 +23,30 @@ function createClerkDevLogger() {
  expiresAt: Date.now() + THROTTLE_DURATION_MS,
  });
  },
+ run: async function (
+ callback,
+ { cacheKey, onSuccessStale = THROTTLE_DURATION_MS, onErrorStale = THROTTLE_DURATION_MS },
+ ) {
+ if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
+ return this.__cache.get(cacheKey)?.data;
+ }
+
+ try {
+ const result = await callback();
+
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onSuccessStale,
+ data: result,
+ });
+ return result;
+ } catch (e) {
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onErrorStale,
+ });
+
+ throw e;
+ }
+ },
  };
  }
 
@@ -37,4 +61,4 @@ export const createConfirmationMessage = () => {
  return `\n\x1b[35m\n[Clerk]:\x1b[0m Your application is running with your claimed keys.\nYou can safely remove the \x1b[35m.clerk/\x1b[0m from your project.\n`;
 };
 
-export const keylessLogger = createClerkDevLogger();
+export const clerkDevelopmentCache = createClerkDevCache();

packages/types/src/clerk.ts

@@ -780,7 +780,7 @@ export type ClerkOptions = ClerkOptionsNavigation &
  * Pass a function that will trigger the unmounting of the Keyless Prompt.
  * It should cause the values of `__internal_claimKeylessApplicationUrl` and `__internal_copyInstanceKeysUrl` to become undefined.
  */
- __internal_keyless_dismissPrompt?: () => Promise<void>;
+ __internal_keyless_dismissPrompt?: (() => Promise<void>) | null;
  };
 
 export interface NavigateOptions {

.changeset/fuzzy-ghosts-kneel.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Mark keyless onboarding as complete when stored keys match explicit keys

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

@@ -1,3 +1,4 @@
+import { joinPaths } from '../../util/path';
 import type { AccountlessApplication } from '../resources/AccountlessApplication';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,4 +11,11 @@ export class AccountlessApplicationAPI extends AbstractAPI {
  path: basePath,
  });
  }
+
+ public async completeAccountlessApplicationOnboarding() {
+ return this.request<AccountlessApplication>({
+ method: 'POST',
+ path: joinPaths(basePath, 'complete'),
+ });
+ }
 }

packages/clerk-js/src/ui/components/KeylessPrompt/index.tsx

@@ -15,7 +15,7 @@ import { useRevalidateEnvironment } from './use-revalidate-environment';
 type KeylessPromptProps = {
  claimUrl: string;
  copyKeysUrl: string;
- onDismiss: (() => Promise<unknown>) | undefined;
+ onDismiss: (() => Promise<unknown>) | undefined | null;
 };
 
 const buttonIdentifierPrefix = `--clerk-keyless-prompt`;

packages/nextjs/src/app-router/keyless-actions.ts

@@ -43,12 +43,12 @@ export async function createOrReadKeylessAction(): Promise<null | Omit<Accountle
  return null;
  }
 
- const { keylessLogger, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
+ const { clerkDevelopmentCache, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
 
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: result.publishableKey,
  msg: createKeylessModeMessage(result),
  });

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 
 import { PromisifiedAuthProvider } from '../../client-boundary/PromisifiedAuthProvider';
 import { getDynamicAuthData } from '../../server/buildClerkProps';
+import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -96,7 +97,7 @@ export async function ClerkProvider(
  const newOrReadKeys = await import('../../server/keyless-node.js')
  .then(mod => mod.createOrReadKeyless())
  .catch(() => null);
- const { keylessLogger, createConfirmationMessage, createKeylessModeMessage } = await import(
+ const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
  '../../server/keyless-log-cache.js'
  );
 
@@ -108,7 +109,8 @@ export async function ClerkProvider(
  publishableKey: newOrReadKeys.publishableKey,
  __internal_keyless_claimKeylessApplicationUrl: newOrReadKeys.claimUrl,
  __internal_keyless_copyInstanceKeysUrl: newOrReadKeys.apiKeysUrl,
- __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : undefined,
+ // Explicitly use `null` instead of `undefined` here to avoid persisting `deleteKeylessAction` during merging of options.
+ __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : null,
  })}
  nonce={await generateNonce()}
  initialState={await generateStatePromise()}
@@ -118,10 +120,37 @@ export async function ClerkProvider(
  );
 
  if (runningWithClaimedKeys) {
+ try {
+ const secretKey = await import('../../server/keyless-node.js').then(
+ mod => mod.safeParseClerkFile()?.secretKey,
+ );
+ if (!secretKey) {
+ // we will ignore it later
+ throw new Error(secretKey);
+ }
+ const client = createClerkClientWithOptions({
+ secretKey,
+ });
+
+ /**
+ * Notifying the dashboard the should runs once. We are controlling this behaviour by caching the result of the request.
+ * If the request fails, it will be considered stale after 10 minutes, otherwise it is cached for 24 hours.
+ */
+ await clerkDevelopmentCache?.run(
+ () => client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding(),
+ {
+ cacheKey: `${newOrReadKeys.publishableKey}_complete`,
+ onSuccessStale: 24 * 60 * 60 * 1000, // 24 hours
+ },
+ );
+ } catch {
+ // ignore
+ }
+
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: `${newOrReadKeys.publishableKey}_claimed`,
  msg: createConfirmationMessage(),
  });
@@ -145,7 +174,7 @@ export async function ClerkProvider(
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: newOrReadKeys.publishableKey,
  msg: createKeylessModeMessage({ ...newOrReadKeys, claimUrl: claimUrl.href }),
  });

packages/nextjs/src/global.d.ts

@@ -44,8 +44,20 @@ declare namespace globalThis {
  // eslint-disable-next-line no-var
  var __clerk_internal_keyless_logger:
  | {
- __cache: Map<string, { expiresAt: number }>;
+ __cache: Map<string, { expiresAt: number; data?: unknown }>;
  log: (param: { cacheKey: string; msg: string }) => void;
+ run: (
+ callback: () => Promise<unknown>,
+ {
+ cacheKey,
+ onSuccessStale,
+ onErrorStale,
+ }: {
+ cacheKey: string;
+ onSuccessStale?: number;
+ onErrorStale?: number;
+ },
+ ) => Promise<unknown>;
  }
  | undefined;
 }

packages/nextjs/src/server/keyless-log-cache.ts

@@ -3,16 +3,16 @@ import { isDevelopmentEnvironment } from '@clerk/shared/utils';
 // 10 minutes in milliseconds
 const THROTTLE_DURATION_MS = 10 * 60 * 1000;
 
-function createClerkDevLogger() {
+function createClerkDevCache() {
  if (!isDevelopmentEnvironment()) {
  return;
  }
 
  if (!global.__clerk_internal_keyless_logger) {
  global.__clerk_internal_keyless_logger = {
- __cache: new Map<string, { expiresAt: number }>(),
+ __cache: new Map<string, { expiresAt: number; data?: unknown }>(),
 
- log: function ({ cacheKey, msg }: { cacheKey: string; msg: string }) {
+ log: function ({ cacheKey, msg }) {
  if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
  return;
  }
@@ -23,6 +23,30 @@ function createClerkDevLogger() {
  expiresAt: Date.now() + THROTTLE_DURATION_MS,
  });
  },
+ run: async function (
+ callback,
+ { cacheKey, onSuccessStale = THROTTLE_DURATION_MS, onErrorStale = THROTTLE_DURATION_MS },
+ ) {
+ if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
+ return this.__cache.get(cacheKey)?.data;
+ }
+
+ try {
+ const result = await callback();
+
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onSuccessStale,
+ data: result,
+ });
+ return result;
+ } catch (e) {
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onErrorStale,
+ });
+
+ throw e;
+ }
+ },
  };
  }
 
@@ -37,4 +61,4 @@ export const createConfirmationMessage = () => {
  return `\n\x1b[35m\n[Clerk]:\x1b[0m Your application is running with your claimed keys.\nYou can safely remove the \x1b[35m.clerk/\x1b[0m from your project.\n`;
 };
 
-export const keylessLogger = createClerkDevLogger();
+export const clerkDevelopmentCache = createClerkDevCache();

packages/types/src/clerk.ts

@@ -780,7 +780,7 @@ export type ClerkOptions = ClerkOptionsNavigation &
  * Pass a function that will trigger the unmounting of the Keyless Prompt.
  * It should cause the values of `__internal_claimKeylessApplicationUrl` and `__internal_copyInstanceKeysUrl` to become undefined.
  */
- __internal_keyless_dismissPrompt?: () => Promise<void>;
+ __internal_keyless_dismissPrompt?: (() => Promise<void>) | null;
  };
 
 export interface NavigateOptions {

.changeset/fuzzy-ghosts-kneel.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Mark keyless onboarding as complete when stored keys match explicit keys

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

@@ -1,3 +1,4 @@
+import { joinPaths } from '../../util/path';
 import type { AccountlessApplication } from '../resources/AccountlessApplication';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,4 +11,11 @@ export class AccountlessApplicationAPI extends AbstractAPI {
  path: basePath,
  });
  }
+
+ public async completeAccountlessApplicationOnboarding() {
+ return this.request<AccountlessApplication>({
+ method: 'POST',
+ path: joinPaths(basePath, 'complete'),
+ });
+ }
 }

packages/clerk-js/src/ui/components/KeylessPrompt/index.tsx

@@ -15,7 +15,7 @@ import { useRevalidateEnvironment } from './use-revalidate-environment';
 type KeylessPromptProps = {
  claimUrl: string;
  copyKeysUrl: string;
- onDismiss: (() => Promise<unknown>) | undefined;
+ onDismiss: (() => Promise<unknown>) | undefined | null;
 };
 
 const buttonIdentifierPrefix = `--clerk-keyless-prompt`;

packages/nextjs/src/app-router/keyless-actions.ts

@@ -43,12 +43,12 @@ export async function createOrReadKeylessAction(): Promise<null | Omit<Accountle
  return null;
  }
 
- const { keylessLogger, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
+ const { clerkDevelopmentCache, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
 
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: result.publishableKey,
  msg: createKeylessModeMessage(result),
  });

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 
 import { PromisifiedAuthProvider } from '../../client-boundary/PromisifiedAuthProvider';
 import { getDynamicAuthData } from '../../server/buildClerkProps';
+import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -96,7 +97,7 @@ export async function ClerkProvider(
  const newOrReadKeys = await import('../../server/keyless-node.js')
  .then(mod => mod.createOrReadKeyless())
  .catch(() => null);
- const { keylessLogger, createConfirmationMessage, createKeylessModeMessage } = await import(
+ const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
  '../../server/keyless-log-cache.js'
  );
 
@@ -108,7 +109,8 @@ export async function ClerkProvider(
  publishableKey: newOrReadKeys.publishableKey,
  __internal_keyless_claimKeylessApplicationUrl: newOrReadKeys.claimUrl,
  __internal_keyless_copyInstanceKeysUrl: newOrReadKeys.apiKeysUrl,
- __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : undefined,
+ // Explicitly use `null` instead of `undefined` here to avoid persisting `deleteKeylessAction` during merging of options.
+ __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : null,
  })}
  nonce={await generateNonce()}
  initialState={await generateStatePromise()}
@@ -118,10 +120,37 @@ export async function ClerkProvider(
  );
 
  if (runningWithClaimedKeys) {
+ try {
+ const secretKey = await import('../../server/keyless-node.js').then(
+ mod => mod.safeParseClerkFile()?.secretKey,
+ );
+ if (!secretKey) {
+ // we will ignore it later
+ throw new Error(secretKey);
+ }
+ const client = createClerkClientWithOptions({
+ secretKey,
+ });
+
+ /**
+ * Notifying the dashboard the should runs once. We are controlling this behaviour by caching the result of the request.
+ * If the request fails, it will be considered stale after 10 minutes, otherwise it is cached for 24 hours.
+ */
+ await clerkDevelopmentCache?.run(
+ () => client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding(),
+ {
+ cacheKey: `${newOrReadKeys.publishableKey}_complete`,
+ onSuccessStale: 24 * 60 * 60 * 1000, // 24 hours
+ },
+ );
+ } catch {
+ // ignore
+ }
+
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: `${newOrReadKeys.publishableKey}_claimed`,
  msg: createConfirmationMessage(),
  });
@@ -145,7 +174,7 @@ export async function ClerkProvider(
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: newOrReadKeys.publishableKey,
  msg: createKeylessModeMessage({ ...newOrReadKeys, claimUrl: claimUrl.href }),
  });

packages/nextjs/src/global.d.ts

@@ -44,8 +44,20 @@ declare namespace globalThis {
  // eslint-disable-next-line no-var
  var __clerk_internal_keyless_logger:
  | {
- __cache: Map<string, { expiresAt: number }>;
+ __cache: Map<string, { expiresAt: number; data?: unknown }>;
  log: (param: { cacheKey: string; msg: string }) => void;
+ run: (
+ callback: () => Promise<unknown>,
+ {
+ cacheKey,
+ onSuccessStale,
+ onErrorStale,
+ }: {
+ cacheKey: string;
+ onSuccessStale?: number;
+ onErrorStale?: number;
+ },
+ ) => Promise<unknown>;
  }
  | undefined;
 }

packages/nextjs/src/server/keyless-log-cache.ts

@@ -3,16 +3,16 @@ import { isDevelopmentEnvironment } from '@clerk/shared/utils';
 // 10 minutes in milliseconds
 const THROTTLE_DURATION_MS = 10 * 60 * 1000;
 
-function createClerkDevLogger() {
+function createClerkDevCache() {
  if (!isDevelopmentEnvironment()) {
  return;
  }
 
  if (!global.__clerk_internal_keyless_logger) {
  global.__clerk_internal_keyless_logger = {
- __cache: new Map<string, { expiresAt: number }>(),
+ __cache: new Map<string, { expiresAt: number; data?: unknown }>(),
 
- log: function ({ cacheKey, msg }: { cacheKey: string; msg: string }) {
+ log: function ({ cacheKey, msg }) {
  if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
  return;
  }
@@ -23,6 +23,30 @@ function createClerkDevLogger() {
  expiresAt: Date.now() + THROTTLE_DURATION_MS,
  });
  },
+ run: async function (
+ callback,
+ { cacheKey, onSuccessStale = THROTTLE_DURATION_MS, onErrorStale = THROTTLE_DURATION_MS },
+ ) {
+ if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
+ return this.__cache.get(cacheKey)?.data;
+ }
+
+ try {
+ const result = await callback();
+
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onSuccessStale,
+ data: result,
+ });
+ return result;
+ } catch (e) {
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onErrorStale,
+ });
+
+ throw e;
+ }
+ },
  };
  }
 
@@ -37,4 +61,4 @@ export const createConfirmationMessage = () => {
  return `\n\x1b[35m\n[Clerk]:\x1b[0m Your application is running with your claimed keys.\nYou can safely remove the \x1b[35m.clerk/\x1b[0m from your project.\n`;
 };
 
-export const keylessLogger = createClerkDevLogger();
+export const clerkDevelopmentCache = createClerkDevCache();

packages/types/src/clerk.ts

@@ -780,7 +780,7 @@ export type ClerkOptions = ClerkOptionsNavigation &
  * Pass a function that will trigger the unmounting of the Keyless Prompt.
  * It should cause the values of `__internal_claimKeylessApplicationUrl` and `__internal_copyInstanceKeysUrl` to become undefined.
  */
- __internal_keyless_dismissPrompt?: () => Promise<void>;
+ __internal_keyless_dismissPrompt?: (() => Promise<void>) | null;
  };
 
 export interface NavigateOptions {

.changeset/fuzzy-ghosts-kneel.md

@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Mark keyless onboarding as complete when stored keys match explicit keys

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

@@ -1,3 +1,4 @@
+import { joinPaths } from '../../util/path';
 import type { AccountlessApplication } from '../resources/AccountlessApplication';
 import { AbstractAPI } from './AbstractApi';
 
@@ -10,4 +11,11 @@ export class AccountlessApplicationAPI extends AbstractAPI {
  path: basePath,
  });
  }
+
+ public async completeAccountlessApplicationOnboarding() {
+ return this.request<AccountlessApplication>({
+ method: 'POST',
+ path: joinPaths(basePath, 'complete'),
+ });
+ }
 }

packages/clerk-js/src/ui/components/KeylessPrompt/index.tsx

@@ -15,7 +15,7 @@ import { useRevalidateEnvironment } from './use-revalidate-environment';
 type KeylessPromptProps = {
  claimUrl: string;
  copyKeysUrl: string;
- onDismiss: (() => Promise<unknown>) | undefined;
+ onDismiss: (() => Promise<unknown>) | undefined | null;
 };
 
 const buttonIdentifierPrefix = `--clerk-keyless-prompt`;

packages/nextjs/src/app-router/keyless-actions.ts

@@ -43,12 +43,12 @@ export async function createOrReadKeylessAction(): Promise<null | Omit<Accountle
  return null;
  }
 
- const { keylessLogger, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
+ const { clerkDevelopmentCache, createKeylessModeMessage } = await import('../server/keyless-log-cache.js');
 
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: result.publishableKey,
  msg: createKeylessModeMessage(result),
  });

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 
 import { PromisifiedAuthProvider } from '../../client-boundary/PromisifiedAuthProvider';
 import { getDynamicAuthData } from '../../server/buildClerkProps';
+import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -96,7 +97,7 @@ export async function ClerkProvider(
  const newOrReadKeys = await import('../../server/keyless-node.js')
  .then(mod => mod.createOrReadKeyless())
  .catch(() => null);
- const { keylessLogger, createConfirmationMessage, createKeylessModeMessage } = await import(
+ const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
  '../../server/keyless-log-cache.js'
  );
 
@@ -108,7 +109,8 @@ export async function ClerkProvider(
  publishableKey: newOrReadKeys.publishableKey,
  __internal_keyless_claimKeylessApplicationUrl: newOrReadKeys.claimUrl,
  __internal_keyless_copyInstanceKeysUrl: newOrReadKeys.apiKeysUrl,
- __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : undefined,
+ // Explicitly use `null` instead of `undefined` here to avoid persisting `deleteKeylessAction` during merging of options.
+ __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : null,
  })}
  nonce={await generateNonce()}
  initialState={await generateStatePromise()}
@@ -118,10 +120,37 @@ export async function ClerkProvider(
  );
 
  if (runningWithClaimedKeys) {
+ try {
+ const secretKey = await import('../../server/keyless-node.js').then(
+ mod => mod.safeParseClerkFile()?.secretKey,
+ );
+ if (!secretKey) {
+ // we will ignore it later
+ throw new Error(secretKey);
+ }
+ const client = createClerkClientWithOptions({
+ secretKey,
+ });
+
+ /**
+ * Notifying the dashboard the should runs once. We are controlling this behaviour by caching the result of the request.
+ * If the request fails, it will be considered stale after 10 minutes, otherwise it is cached for 24 hours.
+ */
+ await clerkDevelopmentCache?.run(
+ () => client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding(),
+ {
+ cacheKey: `${newOrReadKeys.publishableKey}_complete`,
+ onSuccessStale: 24 * 60 * 60 * 1000, // 24 hours
+ },
+ );
+ } catch {
+ // ignore
+ }
+
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: `${newOrReadKeys.publishableKey}_claimed`,
  msg: createConfirmationMessage(),
  });
@@ -145,7 +174,7 @@ export async function ClerkProvider(
  /**
  * Notify developers.
  */
-keylessLogger?.log({
+clerkDevelopmentCache?.log({
  cacheKey: newOrReadKeys.publishableKey,
  msg: createKeylessModeMessage({ ...newOrReadKeys, claimUrl: claimUrl.href }),
  });

packages/nextjs/src/global.d.ts

@@ -44,8 +44,20 @@ declare namespace globalThis {
  // eslint-disable-next-line no-var
  var __clerk_internal_keyless_logger:
  | {
- __cache: Map<string, { expiresAt: number }>;
+ __cache: Map<string, { expiresAt: number; data?: unknown }>;
  log: (param: { cacheKey: string; msg: string }) => void;
+ run: (
+ callback: () => Promise<unknown>,
+ {
+ cacheKey,
+ onSuccessStale,
+ onErrorStale,
+ }: {
+ cacheKey: string;
+ onSuccessStale?: number;
+ onErrorStale?: number;
+ },
+ ) => Promise<unknown>;
  }
  | undefined;
 }

packages/nextjs/src/server/keyless-log-cache.ts

@@ -3,16 +3,16 @@ import { isDevelopmentEnvironment } from '@clerk/shared/utils';
 // 10 minutes in milliseconds
 const THROTTLE_DURATION_MS = 10 * 60 * 1000;
 
-function createClerkDevLogger() {
+function createClerkDevCache() {
  if (!isDevelopmentEnvironment()) {
  return;
  }
 
  if (!global.__clerk_internal_keyless_logger) {
  global.__clerk_internal_keyless_logger = {
- __cache: new Map<string, { expiresAt: number }>(),
+ __cache: new Map<string, { expiresAt: number; data?: unknown }>(),
 
- log: function ({ cacheKey, msg }: { cacheKey: string; msg: string }) {
+ log: function ({ cacheKey, msg }) {
  if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
  return;
  }
@@ -23,6 +23,30 @@ function createClerkDevLogger() {
  expiresAt: Date.now() + THROTTLE_DURATION_MS,
  });
  },
+ run: async function (
+ callback,
+ { cacheKey, onSuccessStale = THROTTLE_DURATION_MS, onErrorStale = THROTTLE_DURATION_MS },
+ ) {
+ if (this.__cache.has(cacheKey) && Date.now() < (this.__cache.get(cacheKey)?.expiresAt || 0)) {
+ return this.__cache.get(cacheKey)?.data;
+ }
+
+ try {
+ const result = await callback();
+
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onSuccessStale,
+ data: result,
+ });
+ return result;
+ } catch (e) {
+ this.__cache.set(cacheKey, {
+ expiresAt: Date.now() + onErrorStale,
+ });
+
+ throw e;
+ }
+ },
  };
  }
 
@@ -37,4 +61,4 @@ export const createConfirmationMessage = () => {
  return `\n\x1b[35m\n[Clerk]:\x1b[0m Your application is running with your claimed keys.\nYou can safely remove the \x1b[35m.clerk/\x1b[0m from your project.\n`;
 };
 
-export const keylessLogger = createClerkDevLogger();
+export const clerkDevelopmentCache = createClerkDevCache();

packages/types/src/clerk.ts

@@ -780,7 +780,7 @@ export type ClerkOptions = ClerkOptionsNavigation &
  * Pass a function that will trigger the unmounting of the Keyless Prompt.
  * It should cause the values of `__internal_claimKeylessApplicationUrl` and `__internal_copyInstanceKeysUrl` to become undefined.
  */
- __internal_keyless_dismissPrompt?: () => Promise<void>;
+ __internal_keyless_dismissPrompt?: (() => Promise<void>) | null;
  };
 
 export interface NavigateOptions {