feat(clerk-js,clerk-react): Support Base authentication

jacekradko · jacekradko · commit b262fc393ccb · 2025-08-26T14:13:50.000-05:00
diff --git a/.changeset/silent-insects-cheat.md b/.changeset/silent-insects-cheat.md
@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/clerk-react': minor
+'@clerk/types': minor
+---
+
+Added support for authentication with Base
diff --git a/packages/clerk-js/package.json b/packages/clerk-js/package.json
@@ -63,6 +63,7 @@
   },
   "browserslist": "last 2 years",
   "dependencies": {
+    "@base-org/account": "2.0.1",
     "@clerk/localizations": "workspace:^",
     "@clerk/shared": "workspace:^",
     "@clerk/types": "workspace:^",
diff --git a/packages/clerk-js/src/core/clerk.ts b/packages/clerk-js/src/core/clerk.ts
@@ -24,6 +24,7 @@ import type {
   __internal_UserVerificationModalProps,
   APIKeysNamespace,
   APIKeysProps,
+  AuthenticateWithBaseParams,
   AuthenticateWithCoinbaseWalletParams,
   AuthenticateWithGoogleOneTapParams,
   AuthenticateWithMetamaskParams,
@@ -42,6 +43,7 @@ import type {
   EnvironmentJSON,
   EnvironmentJSONSnapshot,
   EnvironmentResource,
+  GenerateSignatureParams,
   GoogleOneTapProps,
   HandleEmailLinkVerificationParams,
   HandleOAuthCallbackParams,
@@ -100,6 +102,7 @@ import {
   disabledAPIKeysFeature,
   disabledOrganizationsFeature,
   errorThrower,
+  generateSignatureWithBase,
   generateSignatureWithCoinbaseWallet,
   generateSignatureWithMetamask,
   generateSignatureWithOKXWallet,
@@ -2148,6 +2151,13 @@ export class Clerk implements ClerkInterface {
     });
   };
 
+  public authenticateWithBase = async (props: AuthenticateWithBaseParams = {}): Promise<void> => {
+    await this.authenticateWithWeb3({
+      ...props,
+      strategy: 'web3_base_signature',
+    });
+  };
+
   public authenticateWithOKXWallet = async (props: AuthenticateWithOKXWalletParams = {}): Promise<void> => {
     await this.authenticateWithWeb3({
       ...props,
@@ -2172,12 +2182,21 @@ export class Clerk implements ClerkInterface {
 
     const provider = strategy.replace('web3_', '').replace('_signature', '') as Web3Provider;
     const identifier = await getWeb3Identifier({ provider });
-    const generateSignature =
-      provider === 'metamask'
-        ? generateSignatureWithMetamask
-        : provider === 'coinbase_wallet'
-          ? generateSignatureWithCoinbaseWallet
-          : generateSignatureWithOKXWallet;
+    let generateSignature: (params: GenerateSignatureParams) => Promise<string>;
+    switch (provider) {
+      case 'metamask':
+        generateSignature = generateSignatureWithMetamask;
+        break;
+      case 'base':
+        generateSignature = generateSignatureWithBase;
+        break;
+      case 'coinbase_wallet':
+        generateSignature = generateSignatureWithCoinbaseWallet;
+        break;
+      default:
+        generateSignature = generateSignatureWithOKXWallet;
+        break;
+    }
 
     const makeNavigate = (to: string) => () =>
       customNavigate && typeof customNavigate === 'function' ? customNavigate(to) : this.navigate(to);
diff --git a/packages/clerk-js/src/core/resources/SignIn.ts b/packages/clerk-js/src/core/resources/SignIn.ts
@@ -44,9 +44,11 @@ import type {
 } from '@clerk/types';
 
 import {
+  generateSignatureWithBase,
   generateSignatureWithCoinbaseWallet,
   generateSignatureWithMetamask,
   generateSignatureWithOKXWallet,
+  getBaseIdentifier,
   getCoinbaseWalletIdentifier,
   getMetamaskIdentifier,
   getOKXWalletIdentifier,
@@ -143,11 +145,8 @@ export class SignIn extends BaseResource implements SignInResource {
         } as PhoneCodeConfig;
         break;
       case 'web3_metamask_signature':
-        config = { web3WalletId: factor.web3WalletId } as Web3SignatureConfig;
-        break;
+      case 'web3_base_signature':
       case 'web3_coinbase_wallet_signature':
-        config = { web3WalletId: factor.web3WalletId } as Web3SignatureConfig;
-        break;
       case 'web3_okx_wallet_signature':
         config = { web3WalletId: factor.web3WalletId } as Web3SignatureConfig;
         break;
@@ -361,6 +360,15 @@ export class SignIn extends BaseResource implements SignInResource {
     });
   };
 
+  public authenticateWithBase = async (): Promise<SignInResource> => {
+    const identifier = await getBaseIdentifier();
+    return this.authenticateWithWeb3({
+      identifier,
+      generateSignature: generateSignatureWithBase,
+      strategy: 'web3_base_signature',
+    });
+  };
+
   public authenticateWithOKXWallet = async (): Promise<SignInResource> => {
     const identifier = await getOKXWalletIdentifier();
     return this.authenticateWithWeb3({
diff --git a/packages/clerk-js/src/core/resources/SignUp.ts b/packages/clerk-js/src/core/resources/SignUp.ts
@@ -30,9 +30,11 @@ import type {
 } from '@clerk/types';
 
 import {
+  generateSignatureWithBase,
   generateSignatureWithCoinbaseWallet,
   generateSignatureWithMetamask,
   generateSignatureWithOKXWallet,
+  getBaseIdentifier,
   getCoinbaseWalletIdentifier,
   getMetamaskIdentifier,
   getOKXWalletIdentifier,
@@ -276,6 +278,21 @@ export class SignUp extends BaseResource implements SignUpResource {
     });
   };
 
+  public authenticateWithBase = async (
+    params?: SignUpAuthenticateWithWeb3Params & {
+      legalAccepted?: boolean;
+    },
+  ): Promise<SignUpResource> => {
+    const identifier = await getBaseIdentifier();
+    return this.authenticateWithWeb3({
+      identifier,
+      generateSignature: generateSignatureWithBase,
+      unsafeMetadata: params?.unsafeMetadata,
+      strategy: 'web3_base_signature',
+      legalAccepted: params?.legalAccepted,
+    });
+  };
+
   public authenticateWithOKXWallet = async (
     params?: SignUpAuthenticateWithWeb3Params & {
       legalAccepted?: boolean;
diff --git a/packages/clerk-js/src/utils/web3.ts b/packages/clerk-js/src/utils/web3.ts
@@ -21,7 +21,7 @@ export async function getWeb3Identifier(params: GetWeb3IdentifierParams): Promis
   }
 
   const identifiers = await ethereum.request({ method: 'eth_requestAccounts' });
-  // @ts-ignore
+  // @ts-ignore -- Provider SDKs may return unknown shape; use first address if present
   return (identifiers && identifiers[0]) || '';
 }
 
@@ -58,6 +58,10 @@ export async function getOKXWalletIdentifier(): Promise<string> {
   return await getWeb3Identifier({ provider: 'okx_wallet' });
 }
 
+export async function getBaseIdentifier(): Promise<string> {
+  return await getWeb3Identifier({ provider: 'base' });
+}
+
 type GenerateSignatureParams = {
   identifier: string;
   nonce: string;
@@ -75,6 +79,10 @@ export async function generateSignatureWithOKXWallet(params: GenerateSignaturePa
   return await generateWeb3Signature({ ...params, provider: 'okx_wallet' });
 }
 
+export async function generateSignatureWithBase(params: GenerateSignatureParams): Promise<string> {
+  return await generateWeb3Signature({ ...params, provider: 'base' });
+}
+
 async function getEthereumProvider(provider: Web3Provider) {
   if (provider === 'coinbase_wallet') {
     if (__BUILD_DISABLE_RHC__) {
@@ -90,7 +98,22 @@ async function getEthereumProvider(provider: Web3Provider) {
     });
     return sdk.getProvider();
   }
+  if (provider === 'base') {
+    if (__BUILD_DISABLE_RHC__) {
+      clerkUnsupportedEnvironmentWarning('Base');
+      return null;
+    }
+
+    try {
+      const { createBaseAccountSDK } = await import('@base-org/account');
+      const sdk = createBaseAccountSDK({
+        appName: typeof document !== 'undefined' ? document.title || 'Clerk' : 'Clerk',
+      });
+      return sdk.getProvider();
+    } catch {
+      return null;
+    }
+  }
 
-  const injectedWeb3Providers = getInjectedWeb3Providers();
-  return injectedWeb3Providers.get(provider);
+  return getInjectedWeb3Providers().get(provider);
 }
diff --git a/packages/elements/src/internals/machines/sign-in/start.machine.ts b/packages/elements/src/internals/machines/sign-in/start.machine.ts
@@ -36,6 +36,9 @@ export const SignInStartMachine = setup({
         if (strategy === 'web3_coinbase_wallet_signature') {
           return parent.getSnapshot().context.clerk.client.signIn.authenticateWithCoinbaseWallet();
         }
+        if (strategy === 'web3_base_signature') {
+          return parent.getSnapshot().context.clerk.client.signIn.authenticateWithWallet();
+        }
         if (strategy === 'web3_okx_wallet_signature') {
           return parent.getSnapshot().context.clerk.client.signIn.authenticateWithOKXWallet();
         }
diff --git a/packages/elements/src/react/hooks/use-third-party-provider.hook.ts b/packages/elements/src/react/hooks/use-third-party-provider.hook.ts
@@ -76,6 +76,10 @@ export const useThirdPartyProvider = <
         return ref.send({ type: 'AUTHENTICATE.ENTERPRISE_SSO' });
       }
 
+      if (provider === 'base') {
+        return ref.send({ type: 'AUTHENTICATE.WEB3', strategy: 'web3_base_signature' });
+      }
+
       if (provider === 'metamask') {
         return ref.send({ type: 'AUTHENTICATE.WEB3', strategy: 'web3_metamask_signature' });
       }
diff --git a/packages/elements/src/react/utils/map-scope-to-strategy.ts b/packages/elements/src/react/utils/map-scope-to-strategy.ts
@@ -10,9 +10,15 @@ export function mapScopeToStrategy<T extends `provider:${Strategy}`>(scope: T):
   if (scope === 'provider:metamask') {
     return 'web3_metamask_signature';
   }
+
   if (scope === 'provider:coinbase_wallet') {
     return 'web3_coinbase_wallet_signature';
   }
+
+  if (scope === 'provider:base') {
+    return 'web3_base_signature';
+  }
+
   if (scope === 'provider:okx_wallet') {
     return 'web3_okx_wallet_signature';
   }
diff --git a/packages/react/src/isomorphicClerk.ts b/packages/react/src/isomorphicClerk.ts
@@ -11,6 +11,7 @@ import type {
   __internal_UserVerificationProps,
   APIKeysNamespace,
   APIKeysProps,
+  AuthenticateWithBaseParams,
   AuthenticateWithCoinbaseWalletParams,
   AuthenticateWithGoogleOneTapParams,
   AuthenticateWithMetamaskParams,
@@ -1353,6 +1354,15 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     }
   };
 
+  authenticateWithBase = async (params?: AuthenticateWithBaseParams) => {
+    const callback = () => this.clerkjs?.authenticateWithBase(params);
+    if (this.clerkjs && this.loaded) {
+      return callback() as Promise<void>;
+    } else {
+      this.premountMethodCalls.set('authenticateWithBase', callback);
+    }
+  };
+
   authenticateWithOKXWallet = async (params?: AuthenticateWithOKXWalletParams) => {
     const callback = () => this.clerkjs?.authenticateWithOKXWallet(params);
     if (this.clerkjs && this.loaded) {
diff --git a/packages/shared/src/web3.ts b/packages/shared/src/web3.ts
@@ -6,6 +6,11 @@ export const WEB3_PROVIDERS: Web3ProviderData[] = [
     strategy: 'web3_metamask_signature',
     name: 'MetaMask',
   },
+  {
+    provider: 'base',
+    strategy: 'web3_base_signature',
+    name: 'Base',
+  },
   {
     provider: 'coinbase_wallet',
     strategy: 'web3_coinbase_wallet_signature',
diff --git a/packages/types/src/clerk.ts b/packages/types/src/clerk.ts
@@ -816,6 +816,11 @@ export interface Clerk {
    */
   authenticateWithOKXWallet: (params?: AuthenticateWithOKXWalletParams) => Promise<unknown>;
 
+  /**
+   * Authenticates user using Base Account SDK
+   */
+  authenticateWithBase: (params?: AuthenticateWithBaseParams) => Promise<unknown>;
+
   /**
    * Authenticates user using their Web3 Wallet browser extension
    */
@@ -2178,6 +2183,14 @@ export interface AuthenticateWithGoogleOneTapParams {
   legalAccepted?: boolean;
 }
 
+export interface AuthenticateWithBaseParams {
+  customNavigate?: (to: string) => Promise<unknown>;
+  redirectUrl?: string;
+  signUpContinueUrl?: string;
+  unsafeMetadata?: SignUpUnsafeMetadata;
+  legalAccepted?: boolean;
+}
+
 export interface LoadedClerk extends Clerk {
   client: ClientResource;
 }
diff --git a/packages/types/src/signIn.ts b/packages/types/src/signIn.ts
@@ -115,6 +115,8 @@ export interface SignInResource extends ClerkResource {
 
   authenticateWithOKXWallet: () => Promise<SignInResource>;
 
+  authenticateWithBase: () => Promise<SignInResource>;
+
   authenticateWithPasskey: (params?: AuthenticateWithPasskeyParams) => Promise<SignInResource>;
 
   createEmailLinkFlow: () => CreateEmailLinkFlowReturn<SignInStartEmailLinkFlowParams, SignInResource>;
diff --git a/packages/types/src/signUp.ts b/packages/types/src/signUp.ts
@@ -116,6 +116,7 @@ export interface SignUpResource extends ClerkResource {
   authenticateWithMetamask: (params?: SignUpAuthenticateWithWeb3Params) => Promise<SignUpResource>;
   authenticateWithCoinbaseWallet: (params?: SignUpAuthenticateWithWeb3Params) => Promise<SignUpResource>;
   authenticateWithOKXWallet: (params?: SignUpAuthenticateWithWeb3Params) => Promise<SignUpResource>;
+  authenticateWithBase: (params?: SignUpAuthenticateWithWeb3Params) => Promise<SignUpResource>;
   __internal_toSnapshot: () => SignUpJSONSnapshot;
 
   /**
diff --git a/packages/types/src/web3.ts b/packages/types/src/web3.ts
@@ -9,8 +9,9 @@ export interface Web3ProviderData {
 export type MetamaskWeb3Provider = 'metamask';
 export type CoinbaseWalletWeb3Provider = 'coinbase_wallet';
 export type OKXWalletWeb3Provider = 'okx_wallet';
+export type BaseWeb3Provider = 'base';
 
-export type Web3Provider = MetamaskWeb3Provider | CoinbaseWalletWeb3Provider | OKXWalletWeb3Provider;
+export type Web3Provider = MetamaskWeb3Provider | BaseWeb3Provider | CoinbaseWalletWeb3Provider | OKXWalletWeb3Provider;
 
 /**
  * @deprecated Use `import { WEB3_PROVIDERS } from "@clerk/shared/web3"` instead.
@@ -23,6 +24,11 @@ export const WEB3_PROVIDERS: Web3ProviderData[] = [
     strategy: 'web3_metamask_signature',
     name: 'MetaMask',
   },
+  {
+    provider: 'base',
+    strategy: 'web3_base_signature',
+    name: 'Base',
+  },
   {
     provider: 'coinbase_wallet',
     strategy: 'web3_coinbase_wallet_signature',
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,9 @@ export const SignInStartMachine = setup({`
`36`	`36`	`if (strategy === 'web3_coinbase_wallet_signature') {`
`37`	`37`	`return parent.getSnapshot().context.clerk.client.signIn.authenticateWithCoinbaseWallet();`
`38`	`38`	`}`
	`39`	`+ if (strategy === 'web3_base_signature') {`
	`40`	`+ return parent.getSnapshot().context.clerk.client.signIn.authenticateWithWallet();`
	`41`	`+ }`
`39`	`42`	`if (strategy === 'web3_okx_wallet_signature') {`
`40`	`43`	`return parent.getSnapshot().context.clerk.client.signIn.authenticateWithOKXWallet();`
`41`	`44`	`}`
Original file line number	Diff line number	Diff line change
`@@ -76,6 +76,10 @@ export const useThirdPartyProvider = <`
`76`	`76`	`return ref.send({ type: 'AUTHENTICATE.ENTERPRISE_SSO' });`
`77`	`77`	`}`
`78`	`78`
	`79`	`+ if (provider === 'base') {`
	`80`	`+ return ref.send({ type: 'AUTHENTICATE.WEB3', strategy: 'web3_base_signature' });`
	`81`	`+ }`
	`82`	`+`
`79`	`83`	`if (provider === 'metamask') {`
`80`	`84`	`return ref.send({ type: 'AUTHENTICATE.WEB3', strategy: 'web3_metamask_signature' });`
`81`	`85`	`}`
Original file line number	Diff line number	Diff line change
@@ -10,9 +10,15 @@ export function mapScopeToStrategy<T extends `provider:${Strategy}`>(scope: T):
`10`	`10`	`if (scope === 'provider:metamask') {`
`11`	`11`	`return 'web3_metamask_signature';`
`12`	`12`	`}`
	`13`	`+`
`13`	`14`	`if (scope === 'provider:coinbase_wallet') {`
`14`	`15`	`return 'web3_coinbase_wallet_signature';`
`15`	`16`	`}`
	`17`	`+`
	`18`	`+ if (scope === 'provider:base') {`
	`19`	`+ return 'web3_base_signature';`
	`20`	`+ }`
	`21`	`+`
`16`	`22`	`if (scope === 'provider:okx_wallet') {`
`17`	`23`	`return 'web3_okx_wallet_signature';`
`18`	`24`	`}`