@turnkey/core 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/__clients__/core.mjs

@@ -1,7 +1,7 @@
 import { TurnkeySDKClientBase } from '../__generated__/sdk-client-base.mjs';
-import { TurnkeyErrorCodes, TurnkeyError, TurnkeyNetworkError } from '@turnkey/sdk-types';
-import { SessionKey, DEFAULT_SESSION_EXPIRATION_IN_SECONDS, StamperType, Chain, FilterType, OtpTypeToFilterTypeMap, OtpType, WalletSource, Curve } from '../__types__/base.mjs';
-import { withTurnkeyErrorHandling, isWeb, isReactNative, buildSignUpBody, isEthereumWallet, getPublicKeyFromStampHeader, toExternalTimestamp, isSolanaWallet, getWalletAccountMethods, getHashFunction, getEncodingType, getEncodedMessage, splitSignature, broadcastTransaction, googleISS, isWalletAccountArray, generateWalletAccountsFromAddressFormat } from '../utils.mjs';
+import { TurnkeyErrorCodes, TurnkeyError, TurnkeyNetworkError, AuthAction } from '@turnkey/sdk-types';
+import { SessionKey, DEFAULT_SESSION_EXPIRATION_IN_SECONDS, StamperType, WalletSource, Chain, FilterType, OtpTypeToFilterTypeMap, OtpType, Curve, SignIntent } from '../__types__/base.mjs';
+import { withTurnkeyErrorHandling, isValidPasskeyName, isWeb, isReactNative, buildSignUpBody, findWalletProviderFromAddress, addressFromPublicKey, getCurveTypeFromProvider, getPublicKeyFromStampHeader, toExternalTimestamp, getAuthenticatorAddresses, isEthereumProvider, isSolanaProvider, getHashFunction, getEncodingType, getEncodedMessage, splitSignature, broadcastTransaction, googleISS, isWalletAccountArray, generateWalletAccountsFromAddressFormat } from '../utils.mjs';
 import { createStorageManager } from '../__storage__/base.mjs';
 import { CrossPlatformApiKeyStamper } from '../__stampers__/api/base.mjs';
 import { CrossPlatformPasskeyStamper } from '../__stampers__/passkey/base.mjs';
@@ -21,9 +21,9 @@ class TurnkeyClient {
          * - Handles both web and React Native environments, automatically selecting the appropriate passkey creation flow.
          * - The resulting attestation and challenge can be used to register the passkey with Turnkey.
          *
-         * @param params.name - name of the passkey. If not provided, defaults to "A Passkey".
-         * @param params.displayName - display name for the passkey. If not provided, defaults to "A Passkey".
+         * @param params.name - display name for the passkey (defaults to a generated name based on the current timestamp).
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.challenge - challenge string to use for passkey registration. If not provided, a new challenge will be generated.
          * @returns A promise that resolves to an object containing:
          *   - attestation: attestation object returned from the passkey creation process.
          *   - encodedChallenge: encoded challenge string used for passkey registration.
@@ -31,16 +31,16 @@ class TurnkeyClient {
          */
         this.createPasskey = async (params) => {
             return withTurnkeyErrorHandling(async () => {
-                const name = params?.name || "A Passkey";
-                const displayName = params?.displayName || "A Passkey";
+                const name = isValidPasskeyName(params?.name || `passkey-${Date.now()}`);
                 let passkey;
                 if (isWeb()) {
                     const res = await this.passkeyStamper?.createWebPasskey({
                         publicKey: {
                             user: {
                                 name,
-                                displayName,
+                                displayName: name,
                             },
+                            ...(params?.challenge && { challenge: params.challenge }),
                         },
                     });
                     if (!res) {
@@ -54,7 +54,7 @@ class TurnkeyClient {
                 else if (isReactNative()) {
                     const res = await this.passkeyStamper?.createReactNativePasskey({
                         name,
-                        displayName,
+                        displayName: name,
                     });
                     if (!res) {
                         throw new TurnkeyError("Failed to create React Native passkey", TurnkeyErrorCodes.INTERNAL_ERROR);
@@ -125,21 +125,23 @@ class TurnkeyClient {
          * @param params.publicKey - public key to use for authentication. If not provided, a new key pair will be generated.
          * @param params.sessionKey - session key to use for session creation (defaults to the default session key).
          * @param params.expirationSeconds - session expiration time in seconds (defaults to the configured default).
-         * @returns A promise that resolves to a signed JWT session token.
+         * @returns A promise that resolves to a {@link PasskeyAuthResult}, which includes:
+         *          - `sessionToken`: the signed JWT session token.
+         *          - `credentialId`: an empty string.
          * @throws {TurnkeyError} If there is an error during the passkey login process or if the user cancels the passkey prompt.
          */
         this.loginWithPasskey = async (params) => {
-            let generatedKeyPair = undefined;
+            let generatedPublicKey = undefined;
             return await withTurnkeyErrorHandling(async () => {
-                generatedKeyPair =
+                generatedPublicKey =
                     params?.publicKey || (await this.apiKeyStamper?.createKeyPair());
                 const sessionKey = params?.sessionKey || SessionKey.DefaultSessionkey;
                 const expirationSeconds = params?.expirationSeconds || DEFAULT_SESSION_EXPIRATION_IN_SECONDS;
-                if (!generatedKeyPair) {
+                if (!generatedPublicKey) {
                     throw new TurnkeyError("A publickey could not be found or generated.", TurnkeyErrorCodes.INTERNAL_ERROR);
                 }
                 const sessionResponse = await this.httpClient.stampLogin({
-                    publicKey: generatedKeyPair,
+                    publicKey: generatedPublicKey,
                     organizationId: this.config.organizationId,
                     expirationSeconds,
                 }, StamperType.Passkey);
@@ -147,8 +149,14 @@ class TurnkeyClient {
                     sessionToken: sessionResponse.session,
                     sessionKey,
                 });
-                generatedKeyPair = undefined; // Key pair was successfully used, set to null to prevent cleanup
-                return sessionResponse.session;
+                generatedPublicKey = undefined; // Key pair was successfully used, set to null to prevent cleanup
+                return {
+                    sessionToken: sessionResponse.session,
+                    // TODO: can we return the credentialId here?
+                    // from a quick glance this is going to be difficult
+                    // for now we return an empty string
+                    credentialId: "",
+                };
             }, {
                 errorMessage: "Unable to log in with the provided passkey",
                 errorCode: TurnkeyErrorCodes.PASSKEY_LOGIN_AUTH_ERROR,
@@ -160,9 +168,9 @@ class TurnkeyClient {
                 },
             }, {
                 finallyFn: async () => {
-                    if (generatedKeyPair) {
+                    if (generatedPublicKey) {
                         try {
-                            await this.apiKeyStamper?.deleteKeyPair(generatedKeyPair);
+                            await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
                         }
                         catch (cleanupError) {
                             throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
@@ -180,23 +188,26 @@ class TurnkeyClient {
          * - Automatically generates a new API key pair for authentication and session management.
          * - Stores the resulting session token and manages cleanup of unused key pairs.
          *
+         * @param params.passkeyDisplayName - display name for the passkey (defaults to a generated name based on the current timestamp).
          * @param params.createSubOrgParams - parameters for creating a sub-organization (e.g., authenticators, user metadata).
          * @param params.sessionKey - session key to use for storing the session (defaults to the default session key).
-         * @param params.passkeyDisplayName - display name for the passkey (defaults to a generated name based on the current timestamp).
          * @param params.expirationSeconds - session expiration time in seconds (defaults to the configured default).
-         * @returns A promise that resolves to a signed JWT session token for the new sub-organization.
+         * @param params.challenge - challenge string to use for passkey registration. If not provided, a new challenge will be generated.
+         * @returns A promise that resolves to a {@link PasskeyAuthResult}, which includes:
+         *          - `sessionToken`: the signed JWT session token.
+         *          - `credentialId`: the credential ID associated with the passkey created.
          * @throws {TurnkeyError} If there is an error during passkey creation, sub-organization creation, or session storage.
          */
         this.signUpWithPasskey = async (params) => {
             const { createSubOrgParams, passkeyDisplayName, sessionKey = SessionKey.DefaultSessionkey, expirationSeconds = DEFAULT_SESSION_EXPIRATION_IN_SECONDS, } = params || {};
-            let generatedKeyPair = undefined;
+            let generatedPublicKey = undefined;
             return withTurnkeyErrorHandling(async () => {
-                generatedKeyPair = await this.apiKeyStamper?.createKeyPair();
+                generatedPublicKey = await this.apiKeyStamper?.createKeyPair();
                 const passkeyName = passkeyDisplayName || `passkey-${Date.now()}`;
                 // A passkey will be created automatically when you call this function. The name is passed in
                 const passkey = await this.createPasskey({
                     name: passkeyName,
-                    displayName: passkeyName,
+                    ...(params?.challenge && { challenge: params.challenge }),
                 });
                 if (!passkey) {
                     throw new TurnkeyError("Failed to create passkey: encoded challenge or attestation is missing", TurnkeyErrorCodes.INTERNAL_ERROR);
@@ -215,8 +226,8 @@ class TurnkeyClient {
                         ],
                         apiKeys: [
                             {
-                                apiKeyName: `passkey-auth-${generatedKeyPair}`,
-                                publicKey: generatedKeyPair,
+                                apiKeyName: `passkey-auth-${generatedPublicKey}`,
+                                publicKey: generatedPublicKey,
                                 curveType: "API_KEY_CURVE_P256",
                                 expirationSeconds: "60",
                             },
@@ -228,28 +239,31 @@ class TurnkeyClient {
                     throw new TurnkeyError(`Sign up failed`, TurnkeyErrorCodes.PASSKEY_SIGNUP_AUTH_ERROR);
                 }
                 const newGeneratedKeyPair = await this.apiKeyStamper?.createKeyPair();
-                this.apiKeyStamper?.setPublicKeyOverride(generatedKeyPair);
+                this.apiKeyStamper?.setTemporaryPublicKey(generatedPublicKey);
                 const sessionResponse = await this.httpClient.stampLogin({
                     publicKey: newGeneratedKeyPair,
                     organizationId: this.config.organizationId,
                     expirationSeconds,
                 });
-                await this.apiKeyStamper?.deleteKeyPair(generatedKeyPair);
+                await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
                 await this.storeSession({
                     sessionToken: sessionResponse.session,
                     sessionKey,
                 });
-                generatedKeyPair = undefined; // Key pair was successfully used, set to null to prevent cleanup
-                return sessionResponse.session;
+                generatedPublicKey = undefined; // Key pair was successfully used, set to null to prevent cleanup
+                return {
+                    sessionToken: sessionResponse.session,
+                    credentialId: passkey.attestation.credentialId,
+                };
             }, {
                 errorCode: TurnkeyErrorCodes.PASSKEY_SIGNUP_AUTH_ERROR,
                 errorMessage: "Failed to sign up with passkey",
             }, {
                 finallyFn: async () => {
-                    this.apiKeyStamper?.clearPublicKeyOverride();
-                    if (generatedKeyPair) {
+                    this.apiKeyStamper?.clearTemporaryPublicKey();
+                    if (generatedPublicKey) {
                         try {
-                            await this.apiKeyStamper?.deleteKeyPair(generatedKeyPair);
+                            await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
                         }
                         catch (cleanupError) {
                             throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
@@ -320,24 +334,34 @@ class TurnkeyClient {
             });
         };
         /**
-         * Switches the specified wallet provider to a different blockchain chain.
+         * Switches the wallet provider associated with a given wallet account
+         * to a different chain.
          *
-         * - Requires the wallet manager and its connector to be initialized.
-         * - The wallet provider must have at least one connected address.
-         * - Does nothing if the wallet provider is already on the desired chain.
+         * - Requires the wallet manager and its connector to be initialized
+         * - Only works for connected wallet accounts
+         * - Looks up the provider for the given account address
+         * - Does nothing if the provider is already on the desired chain.
          *
-         * @param walletProvider - wallet provider to switch.
-         * @param chainOrId - target chain as a chain ID string or SwitchableChain object.
+         * @param params.walletAccount - The wallet account whose provider should be switched.
+         * @param params.chainOrId - The target chain, specified as a chain ID string or a SwitchableChain object.
+         * @param params.walletProviders - Optional list of wallet providers to search; falls back to `getWalletProviders()` if omitted.
          * @returns A promise that resolves once the chain switch is complete.
+         *
          * @throws {TurnkeyError} If the wallet manager is uninitialized, the provider is not connected, or the switch fails.
          */
-        this.switchWalletProviderChain = async (walletProvider, chainOrId) => {
+        this.switchWalletAccountChain = async (params) => {
+            const { walletAccount, chainOrId, walletProviders } = params;
             return withTurnkeyErrorHandling(async () => {
                 if (!this.walletManager?.connector) {
                     throw new TurnkeyError("Wallet connector is not initialized", TurnkeyErrorCodes.WALLET_MANAGER_COMPONENT_NOT_INITIALIZED);
                 }
-                if (walletProvider.connectedAddresses.length === 0) {
-                    throw new TurnkeyError("You can not switch chains for a provider that is not connected", TurnkeyErrorCodes.INVALID_REQUEST);
+                if (walletAccount.source === WalletSource.Embedded) {
+                    throw new TurnkeyError("You can only switch chains for connected wallet accounts", TurnkeyErrorCodes.NOT_FOUND);
+                }
+                const providers = walletProviders ?? (await this.getWalletProviders());
+                const walletProvider = findWalletProviderFromAddress(walletAccount.address, providers);
+                if (!walletProvider) {
+                    throw new TurnkeyError("Wallet provider not found", TurnkeyErrorCodes.SWITCH_WALLET_CHAIN_ERROR);
                 }
                 // if the wallet provider is already on the desired chain, do nothing
                 if (walletProvider.chainInfo.namespace === chainOrId) {
@@ -362,7 +386,9 @@ class TurnkeyClient {
          * @param params.publicKey - optional public key to associate with the session (generated if not provided).
          * @param params.sessionKey - optional key to store the session under (defaults to the default session key).
          * @param params.expirationSeconds - optional session expiration time in seconds (defaults to the configured default).
-         * @returns A promise that resolves to the created session token.
+         * @returns A promise that resolves to a {@link WalletAuthResult}, which includes:
+         *          - `sessionToken`: the signed JWT session token.
+         *          - `address`: the authenticated wallet address.
          * @throws {TurnkeyError} If the wallet stamper is uninitialized, a public key cannot be found or generated, or login fails.
          */
         this.loginWithWallet = async (params) => {
@@ -387,14 +413,19 @@ class TurnkeyClient {
                     sessionToken: sessionResponse.session,
                     sessionKey,
                 });
-                return sessionResponse.session;
+                // TODO (Moe): What happens if a user connects to MetaMask on Ethereum,
+                // then switches to a Solana account within MetaMask? Will this flow break?
+                return {
+                    sessionToken: sessionResponse.session,
+                    address: addressFromPublicKey(walletProvider.chainInfo.namespace, publicKey),
+                };
             }, {
                 errorMessage: "Unable to log in with the provided wallet",
                 errorCode: TurnkeyErrorCodes.WALLET_LOGIN_AUTH_ERROR,
             }, {
                 finallyFn: async () => {
                     // Clean up the generated key pair if it wasn't successfully used
-                    this.apiKeyStamper?.clearPublicKeyOverride();
+                    this.apiKeyStamper?.clearTemporaryPublicKey();
                     if (publicKey) {
                         try {
                             await this.apiKeyStamper?.deleteKeyPair(publicKey);
@@ -419,17 +450,19 @@ class TurnkeyClient {
          * @param params.createSubOrgParams - parameters for creating a sub-organization (e.g., authenticators, user metadata).
          * @param params.sessionKey - session key to use for storing the session (defaults to the default session key).
          * @param params.expirationSeconds - session expiration time in seconds (defaults to the configured default).
-         * @returns A promise that resolves to a signed JWT session token for the new sub-organization.
+         * @returns A promise that resolves to a {@link WalletAuthResult}, which includes:
+         *          - `sessionToken`: the signed JWT session token.
+         *          - `address`: the authenticated wallet address.
          * @throws {TurnkeyError} If there is an error during wallet authentication, sub-organization creation, session storage, or cleanup.
          */
         this.signUpWithWallet = async (params) => {
             const { walletProvider, createSubOrgParams, sessionKey = SessionKey.DefaultSessionkey, expirationSeconds = DEFAULT_SESSION_EXPIRATION_IN_SECONDS, } = params;
-            let generatedKeyPair = undefined;
+            let generatedPublicKey = undefined;
             return withTurnkeyErrorHandling(async () => {
                 if (!this.walletManager?.stamper) {
                     throw new TurnkeyError("Wallet stamper is not initialized", TurnkeyErrorCodes.WALLET_MANAGER_COMPONENT_NOT_INITIALIZED);
                 }
-                generatedKeyPair = await this.apiKeyStamper?.createKeyPair();
+                generatedPublicKey = await this.apiKeyStamper?.createKeyPair();
                 this.walletManager.stamper.setProvider(walletProvider.interfaceType, walletProvider);
                 const publicKey = await this.walletManager.stamper.getPublicKey(walletProvider.interfaceType, walletProvider);
                 if (!publicKey) {
@@ -442,13 +475,11 @@ class TurnkeyClient {
                             {
                                 apiKeyName: `wallet-auth:${publicKey}`,
                                 publicKey: publicKey,
-                                curveType: isEthereumWallet(walletProvider)
-                                    ? "API_KEY_CURVE_SECP256K1"
-                                    : "API_KEY_CURVE_ED25519",
+                                curveType: getCurveTypeFromProvider(walletProvider),
                             },
                             {
-                                apiKeyName: `wallet-auth-${generatedKeyPair}`,
-                                publicKey: generatedKeyPair,
+                                apiKeyName: `wallet-auth-${generatedPublicKey}`,
+                                publicKey: generatedPublicKey,
                                 curveType: "API_KEY_CURVE_P256",
                                 expirationSeconds: "60",
                             },
@@ -460,29 +491,34 @@ class TurnkeyClient {
                     throw new TurnkeyError(`Sign up failed`, TurnkeyErrorCodes.WALLET_SIGNUP_AUTH_ERROR);
                 }
                 const newGeneratedKeyPair = await this.apiKeyStamper?.createKeyPair();
-                this.apiKeyStamper?.setPublicKeyOverride(generatedKeyPair);
+                this.apiKeyStamper?.setTemporaryPublicKey(generatedPublicKey);
                 const sessionResponse = await this.httpClient.stampLogin({
                     publicKey: newGeneratedKeyPair,
                     organizationId: this.config.organizationId,
                     expirationSeconds,
                 });
-                await this.apiKeyStamper?.deleteKeyPair(generatedKeyPair);
+                await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
                 await this.storeSession({
                     sessionToken: sessionResponse.session,
                     sessionKey,
                 });
-                generatedKeyPair = undefined; // Key pair was successfully used, set to null to prevent cleanup
-                return sessionResponse.session;
+                generatedPublicKey = undefined; // Key pair was successfully used, set to null to prevent cleanup
+                // TODO (Moe): What happens if a user connects to MetaMask on Ethereum,
+                // then switches to a Solana account within MetaMask? Will this flow break?
+                return {
+                    sessionToken: sessionResponse.session,
+                    address: addressFromPublicKey(walletProvider.chainInfo.namespace, publicKey),
+                };
             }, {
                 errorMessage: "Failed to sign up with wallet",
                 errorCode: TurnkeyErrorCodes.WALLET_SIGNUP_AUTH_ERROR,
             }, {
                 finallyFn: async () => {
                     // Clean up the generated key pair if it wasn't successfully used
-                    this.apiKeyStamper?.clearPublicKeyOverride();
-                    if (generatedKeyPair) {
+                    this.apiKeyStamper?.clearTemporaryPublicKey();
+                    if (generatedPublicKey) {
                         try {
-                            await this.apiKeyStamper?.deleteKeyPair(generatedKeyPair);
+                            await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
                         }
                         catch (cleanupError) {
                             throw new TurnkeyError("Failed to clean up generated key pair", TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
@@ -505,7 +541,10 @@ class TurnkeyClient {
          * @param params.createSubOrgParams - optional parameters for creating a sub-organization (e.g., authenticators, user metadata).
          * @param params.sessionKey - session key to use for storing the session (defaults to the default session key).
          * @param params.expirationSeconds - session expiration time in seconds (defaults to the configured default).
-         * @returns A promise that resolves to a signed JWT session token for the sub-organization (new or existing).
+         * @returns A promise that resolves to an object containing:
+         *          - `sessionToken`: the signed JWT session token.
+         *          - `address`: the authenticated wallet address.
+         *          - `action`: whether the flow resulted in a login or signup ({@link AuthAction}).
          * @throws {TurnkeyError} If there is an error during wallet authentication, sub-organization creation, or session storage.
          */
         this.loginOrSignupWithWallet = async (params) => {
@@ -513,19 +552,19 @@ class TurnkeyClient {
             const sessionKey = params.sessionKey || SessionKey.DefaultSessionkey;
             const walletProvider = params.walletProvider;
             const expirationSeconds = params.expirationSeconds || DEFAULT_SESSION_EXPIRATION_IN_SECONDS;
-            let generatedKeyPair = undefined;
+            let generatedPublicKey = undefined;
             return withTurnkeyErrorHandling(async () => {
                 if (!this.walletManager?.stamper) {
                     throw new TurnkeyError("Wallet stamper is not initialized", TurnkeyErrorCodes.WALLET_MANAGER_COMPONENT_NOT_INITIALIZED);
                 }
-                generatedKeyPair = await this.apiKeyStamper?.createKeyPair();
+                generatedPublicKey = await this.apiKeyStamper?.createKeyPair();
                 this.walletManager.stamper.setProvider(walletProvider.interfaceType, walletProvider);
-                // here we sign the request with the wallet, but we don't send it to the Turnkey yet
+                // here we sign the request with the wallet, but we don't send it to Turnkey yet
                 // this is because we need to check if the subOrg exists first, and create one if it doesn't
-                // once we have the subOrg for the publicKey, we then can send the request to the Turnkey
+                // once we have the subOrg for the publicKey, we then can send the request to Turnkey
                 const signedRequest = await withTurnkeyErrorHandling(async () => {
                     return this.httpClient.stampStampLogin({
-                        publicKey: generatedKeyPair,
+                        publicKey: generatedPublicKey,
                         organizationId: this.config.organizationId,
                         expirationSeconds,
                     }, StamperType.Wallet);
@@ -562,7 +601,7 @@ class TurnkeyClient {
                         throw new TurnkeyError(`Unsupported interface type: ${walletProvider.interfaceType}`, TurnkeyErrorCodes.INVALID_REQUEST);
                 }
                 // here we check if the subOrg exists and create one
-                // then we send off the stamped request to the Turnkey
+                // then we send off the stamped request to Turnkey
                 const accountRes = await this.httpClient.proxyGetAccount({
                     filterType: FilterType.PublicKey,
                     filterValue: publicKey,
@@ -580,9 +619,7 @@ class TurnkeyClient {
                                 {
                                     apiKeyName: `wallet-auth:${publicKey}`,
                                     publicKey: publicKey,
-                                    curveType: isEthereumWallet(walletProvider)
-                                        ? "API_KEY_CURVE_SECP256K1"
-                                        : "API_KEY_CURVE_ED25519",
+                                    curveType: getCurveTypeFromProvider(walletProvider),
                                 },
                             ],
                         },
@@ -592,7 +629,7 @@ class TurnkeyClient {
                         throw new TurnkeyError(`Sign up failed`, TurnkeyErrorCodes.WALLET_SIGNUP_AUTH_ERROR);
                     }
                 }
-                // now we can send the stamped request to the Turnkey
+                // now we can send the stamped request to Turnkey
                 const headers = {
                     "Content-Type": "application/json",
                     [signedRequest.stamp.stampHeaderName]: signedRequest.stamp.stampHeaderValue,
@@ -615,14 +652,19 @@ class TurnkeyClient {
                     sessionToken: sessionToken,
                     sessionKey,
                 });
-                return sessionToken;
+                return {
+                    sessionToken: sessionToken,
+                    address: addressFromPublicKey(walletProvider.chainInfo.namespace, publicKey),
+                    // if the subOrganizationId exists, it means the user is logging in
+                    action: subOrganizationId ? AuthAction.LOGIN : AuthAction.SIGNUP,
+                };
             }, {
                 errorCode: TurnkeyErrorCodes.WALLET_LOGIN_OR_SIGNUP_ERROR,
                 errorMessage: "Failed to log in or sign up with wallet",
                 catchFn: async () => {
-                    if (generatedKeyPair) {
+                    if (generatedPublicKey) {
                         try {
-                            await this.apiKeyStamper?.deleteKeyPair(generatedKeyPair);
+                            await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
                         }
                         catch (cleanupError) {
                             throw new TurnkeyError(`Failed to clean up generated key pair`, TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
@@ -724,7 +766,8 @@ class TurnkeyClient {
          * @param params.publicKey - public key to use for authentication. If not provided, a new key pair will be generated.
          * @param params.invalidateExisting - flag to invalidate existing session for the user.
          * @param params.sessionKey - session key to use for session creation (defaults to the default session key).
-         * @returns A promise that resolves to a signed JWT session token.
+         * @returns A promise that resolves to a {@link BaseAuthResult}, which includes:
+         *          - `sessionToken`: the signed JWT session token.
          * @throws {TurnkeyError} If there is an error during the OTP login process or if key pair cleanup fails.
          */
         this.loginWithOtp = async (params) => {
@@ -746,7 +789,9 @@ class TurnkeyClient {
                     sessionToken: loginRes.session,
                     sessionKey,
                 });
-                return loginRes.session;
+                return {
+                    sessionToken: loginRes.session,
+                };
             }, {
                 errorMessage: "Failed to log in with OTP",
                 errorCode: TurnkeyErrorCodes.OTP_LOGIN_ERROR,
@@ -778,7 +823,8 @@ class TurnkeyClient {
          * @param params.createSubOrgParams - parameters for creating a sub-organization (e.g., authenticators, user metadata).
          * @param params.invalidateExisting - flag to invalidate existing session for the user.
          * @param params.sessionKey - session key to use for session creation (defaults to the default session key).
-         * @returns A promise that resolves to a signed JWT session token for the new sub-organization.
+         * @returns A promise that resolves to a {@link BaseAuthResult}, which includes:
+         *          - `sessionToken`: the signed JWT session token.
          * @throws {TurnkeyError} If there is an error during the OTP sign-up process or session storage.
          */
         this.signUpWithOtp = async (params) => {
@@ -793,14 +839,14 @@ class TurnkeyClient {
                 },
             });
             return withTurnkeyErrorHandling(async () => {
-                const generatedKeyPair = await this.apiKeyStamper?.createKeyPair();
+                const generatedPublicKey = await this.apiKeyStamper?.createKeyPair();
                 const res = await this.httpClient.proxySignup(signUpBody);
                 if (!res) {
                     throw new TurnkeyError(`Auth proxy OTP sign up failed`, TurnkeyErrorCodes.OTP_SIGNUP_ERROR);
                 }
                 return await this.loginWithOtp({
                     verificationToken,
-                    publicKey: generatedKeyPair,
+                    publicKey: generatedPublicKey,
                     ...(invalidateExisting && { invalidateExisting }),
                     ...(sessionKey && { sessionKey }),
                 });
@@ -826,7 +872,10 @@ class TurnkeyClient {
          * @param params.invalidateExisting - flag to invalidate existing sessions for the user.
          * @param params.sessionKey - session key to use for session creation (defaults to the default session key).
          * @param params.createSubOrgParams - parameters for sub-organization creation (e.g., authenticators, user metadata).
-         * @returns A promise that resolves to a signed JWT session token for the user.
+         * @returns A promise that resolves to an object containing:
+         *          - `sessionToken`: the signed JWT session token.
+         *          - `verificationToken`: the OTP verification token.
+         *          - `action`: whether the flow resulted in a login or signup ({@link AuthAction}).
          * @throws {TurnkeyError} If there is an error during OTP verification, sign-up, or login.
          */
         this.completeOtp = async (params) => {
@@ -842,24 +891,32 @@ class TurnkeyClient {
                     throw new TurnkeyError("No verification token returned from OTP verification", TurnkeyErrorCodes.VERIFY_OTP_ERROR);
                 }
                 if (!subOrganizationId) {
-                    return await this.signUpWithOtp({
+                    const signUpRes = await this.signUpWithOtp({
                         verificationToken,
-                        contact: contact,
-                        otpType: otpType,
-                        ...(createSubOrgParams && {
-                            createSubOrgParams,
-                        }),
+                        contact,
+                        otpType,
+                        ...(createSubOrgParams && { createSubOrgParams }),
                         ...(invalidateExisting && { invalidateExisting }),
                         ...(sessionKey && { sessionKey }),
                     });
+                    return {
+                        ...signUpRes,
+                        verificationToken,
+                        action: AuthAction.SIGNUP,
+                    };
                 }
                 else {
-                    return await this.loginWithOtp({
+                    const loginRes = await this.loginWithOtp({
                         verificationToken,
                         ...(publicKey && { publicKey }),
                         ...(invalidateExisting && { invalidateExisting }),
                         ...(sessionKey && { sessionKey }),
                     });
+                    return {
+                        ...loginRes,
+                        verificationToken,
+                        action: AuthAction.LOGIN,
+                    };
                 }
             }, {
                 errorMessage: "Failed to complete OTP process",
@@ -876,12 +933,14 @@ class TurnkeyClient {
          * - Handles session storage and management, and supports invalidating existing sessions if specified.
          *
          * @param params.oidcToken - OIDC token received after successful authentication with the OAuth provider.
-         * @param params.publicKey - public key to use for authentication. Must be generated prior to calling this function.
+         * @param params.publicKey - public key to use for authentication. Must be generated prior to calling this function, this is because the OIDC nonce has to be set to `sha256(publicKey)`.
          * @param params.providerName - name of the OAuth provider (defaults to a generated name with a timestamp).
          * @param params.sessionKey - session key to use for session creation (defaults to the default session key).
          * @param params.invalidateExisting - flag to invalidate existing sessions for the user.
          * @param params.createSubOrgParams - parameters for sub-organization creation (e.g., authenticators, user metadata).
-         * @returns A promise that resolves to a signed JWT session token for the user.
+         * @returns A promise that resolves to an object containing:
+         *          - `sessionToken`: the signed JWT session token.
+         *          - `action`: whether the flow resulted in a login or signup ({@link AuthAction}).
          * @throws {TurnkeyError} If there is an error during the OAuth completion process, such as account lookup, sign-up, or login.
          */
         this.completeOauth = async (params) => {
@@ -896,22 +955,31 @@ class TurnkeyClient {
                 }
                 const subOrganizationId = accountRes.organizationId;
                 if (subOrganizationId) {
-                    return this.loginWithOauth({
+                    const loginRes = await this.loginWithOauth({
                         oidcToken,
                         publicKey,
                         invalidateExisting,
                         sessionKey,
                     });
+                    return {
+                        ...loginRes,
+                        action: AuthAction.LOGIN,
+                    };
                 }
                 else {
-                    return this.signUpWithOauth({
+                    const signUpRes = await this.signUpWithOauth({
                         oidcToken,
                         publicKey,
                         providerName,
+                        sessionKey,
                         ...(createSubOrgParams && {
                             createSubOrgParams,
                         }),
                     });
+                    return {
+                        ...signUpRes,
+                        action: AuthAction.SIGNUP,
+                    };
                 }
             }, {
                 errorMessage: "Failed to complete OAuth process",
@@ -930,7 +998,8 @@ class TurnkeyClient {
          * @param params.publicKey - public key to use for authentication. Must be generated prior to calling this function.
          * @param params.invalidateExisting - flag to invalidate existing sessions for the user.
          * @param params.sessionKey - session key to use for session creation (defaults to the default session key).
-         * @returns A promise that resolves to a signed JWT session token.
+         * @returns A promise that resolves to a {@link BaseAuthResult}, which includes:
+         *          - `sessionToken`: the signed JWT session token.
          * @throws {TurnkeyError} If there is an error during the OAuth login process or if key pair cleanup fails.
          */
         this.loginWithOauth = async (params) => {
@@ -954,7 +1023,7 @@ class TurnkeyClient {
                     sessionToken: loginRes.session,
                     sessionKey,
                 });
-                return loginRes.session;
+                return { sessionToken: loginRes.session };
             }, {
                 errorMessage: "Failed to complete OAuth login",
                 errorCode: TurnkeyErrorCodes.OAUTH_LOGIN_ERROR,
@@ -990,11 +1059,12 @@ class TurnkeyClient {
          * @param params.providerName - name of the OAuth provider (e.g., "Google", "Apple").
          * @param params.createSubOrgParams - parameters for sub-organization creation (e.g., authenticators, user metadata).
          * @param params.sessionKey - session key to use for session creation (defaults to the default session key).
-         * @returns A promise that resolves to a signed JWT session token for the new sub-organization.
+         * @returns A promise that resolves to a {@link BaseAuthResult}, which includes:
+         *          - `sessionToken`: the signed JWT session token.
          * @throws {TurnkeyError} If there is an error during the OAuth sign-up or login process.
          */
         this.signUpWithOauth = async (params) => {
-            const { oidcToken, publicKey, providerName, createSubOrgParams } = params;
+            const { oidcToken, publicKey, providerName, createSubOrgParams, sessionKey, } = params;
             return withTurnkeyErrorHandling(async () => {
                 const signUpBody = buildSignUpBody({
                     createSubOrgParams: {
@@ -1014,6 +1084,7 @@ class TurnkeyClient {
                 return await this.loginWithOauth({
                     oidcToken,
                     publicKey: publicKey,
+                    ...(sessionKey && { sessionKey }),
                 });
             }, {
                 errorMessage: "Failed to sign up with OAuth",
@@ -1030,11 +1101,12 @@ class TurnkeyClient {
          * - Optionally allows stamping the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
          *
          * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @param params.walletProviders - array of wallet providers to use for fetching wallets.
          * @returns A promise that resolves to an array of `Wallet` objects.
          * @throws {TurnkeyError} If no active session is found or if there is an error fetching wallets.
          */
         this.fetchWallets = async (params) => {
-            const { stampWith } = params || {};
+            const { stampWith, walletProviders } = params || {};
             const session = await this.storageManager.getActiveSession();
             if (!session) {
                 throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
@@ -1060,9 +1132,11 @@ class TurnkeyClient {
                 // if wallet connecting is disabled we return only embedded wallets
                 if (!this.walletManager?.connector)
                     return embedded;
-                const providers = await this.getWalletProviders();
+                const providers = walletProviders ?? (await this.getWalletProviders());
                 const groupedProviders = new Map();
                 for (const provider of providers) {
+                    // connected wallets don't all have some uuid we can use for the walletId
+                    // so what we do is we use a normalized version of the name for the wallet, like "metamask" or "phantom-wallet"
                     const walletId = provider.info?.name?.toLowerCase().replace(/\s+/g, "-") ||
                         "unknown";
                     const group = groupedProviders.get(walletId) || [];
@@ -1144,31 +1218,69 @@ class TurnkeyClient {
                     return [];
                 const connected = [];
                 const providers = walletProviders ?? (await this.getWalletProviders());
+                // Context: connected wallets don't all have some uuid we can use for the walletId so what
+                //          we do is we use a normalized version of the name for the wallet, like "metamask"
+                //          or "phantom-wallet"
+                //
+                // when fetching accounts, we select all providers with this normalized walletId.
+                // A single wallet can map to multiple providers if it supports multiple chains
+                // (e.g. MetaMask for Ethereum and MetaMask for Solana)
                 const matching = providers.filter((p) => p.info?.name?.toLowerCase().replace(/\s+/g, "-") ===
                     wallet.walletId && p.connectedAddresses.length > 0);
+                const sign = this.walletManager.connector.sign.bind(this.walletManager.connector);
+                const user = await this.fetchUser({
+                    stampWith,
+                });
+                const { ethereum: ethereumAddresses, solana: solanaAddresses } = getAuthenticatorAddresses(user);
                 for (const provider of matching) {
                     const timestamp = toExternalTimestamp();
                     for (const address of provider.connectedAddresses) {
-                        const account = {
-                            walletAccountId: `${wallet.walletId}-${provider.interfaceType}-${address}`,
-                            organizationId: session.organizationId,
-                            walletId: wallet.walletId,
-                            curve: isEthereumWallet(provider)
-                                ? Curve.SECP256K1
-                                : Curve.ED25519,
-                            pathFormat: "PATH_FORMAT_BIP32",
-                            path: WalletSource.Connected,
-                            source: WalletSource.Connected,
-                            addressFormat: isEthereumWallet(provider)
-                                ? "ADDRESS_FORMAT_ETHEREUM"
-                                : "ADDRESS_FORMAT_SOLANA",
-                            address,
-                            createdAt: timestamp,
-                            updatedAt: timestamp,
-                            ...getWalletAccountMethods(this.walletManager.connector.sign.bind(this.walletManager.connector), provider),
-                            ...(isSolanaWallet(provider) && { publicKey: address }),
-                        };
-                        connected.push(account);
+                        if (isEthereumProvider(provider)) {
+                            const evmAccount = {
+                                walletAccountId: `${wallet.walletId}-${provider.interfaceType}-${address}`,
+                                organizationId: session.organizationId,
+                                walletId: wallet.walletId,
+                                pathFormat: "PATH_FORMAT_BIP32",
+                                path: WalletSource.Connected,
+                                source: WalletSource.Connected,
+                                address,
+                                createdAt: timestamp,
+                                updatedAt: timestamp,
+                                // ethereum specific
+                                curve: Curve.SECP256K1,
+                                addressFormat: "ADDRESS_FORMAT_ETHEREUM",
+                                chainInfo: provider.chainInfo,
+                                isAuthenticator: ethereumAddresses.includes(address.toLowerCase()),
+                                signMessage: (msg) => sign(msg, provider, SignIntent.SignMessage),
+                                signAndSendTransaction: (tx) => sign(tx, provider, SignIntent.SignAndSendTransaction),
+                            };
+                            connected.push(evmAccount);
+                            continue;
+                        }
+                        if (isSolanaProvider(provider)) {
+                            const solAccount = {
+                                walletAccountId: `${wallet.walletId}-${provider.interfaceType}-${address}`,
+                                organizationId: session.organizationId,
+                                walletId: wallet.walletId,
+                                pathFormat: "PATH_FORMAT_BIP32",
+                                path: WalletSource.Connected,
+                                source: WalletSource.Connected,
+                                address,
+                                createdAt: timestamp,
+                                updatedAt: timestamp,
+                                // solana specific
+                                publicKey: address,
+                                curve: Curve.ED25519,
+                                addressFormat: "ADDRESS_FORMAT_SOLANA",
+                                chainInfo: provider.chainInfo,
+                                isAuthenticator: solanaAddresses.includes(address),
+                                signMessage: (msg) => sign(msg, provider, SignIntent.SignMessage),
+                                signTransaction: (tx) => sign(tx, provider, SignIntent.SignTransaction),
+                            };
+                            connected.push(solAccount);
+                            continue;
+                        }
+                        throw new Error(`Unsupported wallet chain: ${provider.chainInfo}. Supported chains are Ethereum and Solana.`);
                     }
                 }
                 return connected;
@@ -1177,6 +1289,33 @@ class TurnkeyClient {
                 errorCode: TurnkeyErrorCodes.FETCH_WALLET_ACCOUNTS_ERROR,
             });
         };
+        /**
+         * Fetches all private keys for the current user.
+         *
+         * - Retrieves private keys from the Turnkey API.
+         * - Supports stamping the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         *
+         * @param params.stampWith - parameter to stamp the request with a specific stamper (StamperType.Passkey, StamperType.ApiKey, or StamperType.Wallet).
+         * @returns A promise that resolves to an array of `v1PrivateKey` objects.
+         * @throws {TurnkeyError} If no active session is found or if there is an error fetching private keys.
+         */
+        this.fetchPrivateKeys = async (params) => {
+            const { stampWith } = params || {};
+            const session = await this.storageManager.getActiveSession();
+            if (!session) {
+                throw new TurnkeyError("No active session found. Please log in first.", TurnkeyErrorCodes.NO_SESSION_FOUND);
+            }
+            return withTurnkeyErrorHandling(async () => {
+                const res = await this.httpClient.getPrivateKeys({ organizationId: session.organizationId }, stampWith);
+                if (!res) {
+                    throw new TurnkeyError("Failed to fetch private keys", TurnkeyErrorCodes.BAD_RESPONSE);
+                }
+                return res.privateKeys;
+            }, {
+                errorMessage: "Failed to fetch private keys",
+                errorCode: TurnkeyErrorCodes.FETCH_PRIVATE_KEYS_ERROR,
+            });
+        };
         /**
          * Signs a message using the specified wallet account.
          *
@@ -1266,15 +1405,16 @@ class TurnkeyClient {
             const { walletAccount, unsignedTransaction, transactionType, stampWith } = params;
             return withTurnkeyErrorHandling(async () => {
                 if (walletAccount.source === WalletSource.Connected) {
-                    // this is a connected wallet account
-                    if (!walletAccount.signTransaction) {
-                        const isEthereum = walletAccount.addressFormat === "ADDRESS_FORMAT_ETHEREUM";
-                        const reason = isEthereum
-                            ? "Ethereum connected wallets do not support raw transaction signing due to EIP-1193 limitations."
-                            : "This connected wallet does not support raw transaction signing.";
-                        throw new TurnkeyError(`Failed to sign transaction: ${reason} ${isEthereum ? "Use signAndSendTransaction instead." : ""}`, TurnkeyErrorCodes.SIGN_TRANSACTION_ERROR);
+                    switch (walletAccount.chainInfo.namespace) {
+                        case Chain.Ethereum:
+                            throw new TurnkeyError("Ethereum connected wallets do not support raw transaction signing. Use signAndSendTransaction instead.", TurnkeyErrorCodes.INVALID_REQUEST);
+                        case Chain.Solana:
+                            // not sure why typescript isn't inferring the type here
+                            // if namespace is Chain.Solana, then it must be a ConnectedSolanaWalletAccount
+                            return walletAccount.signTransaction(unsignedTransaction);
+                        default:
+                            throw new TurnkeyError("Unsupported connected wallet type.", TurnkeyErrorCodes.INVALID_REQUEST);
                     }
-                    return await walletAccount?.signTransaction(unsignedTransaction);
                 }
                 // this is an embedded wallet account
                 const signTransaction = await this.httpClient.signTransaction({
@@ -1313,19 +1453,17 @@ class TurnkeyClient {
             return withTurnkeyErrorHandling(async () => {
                 if (walletAccount.source === WalletSource.Connected) {
                     // this is a connected wallet account
-                    switch (transactionType) {
-                        case "TRANSACTION_TYPE_ETHEREUM":
-                            if (!walletAccount.signAndSendTransaction) {
-                                throw new TurnkeyError("This connected wallet does not support signAndSendTransaction.", TurnkeyErrorCodes.SIGN_AND_SEND_TRANSACTION_ERROR);
-                            }
+                    switch (walletAccount.chainInfo.namespace) {
+                        case Chain.Ethereum:
+                            // not sure why typescript isn't inferring the type here
+                            // if namespace is Chain.Ethereum, then it must be a ConnectedEthereumWalletAccount
                             return await walletAccount.signAndSendTransaction(unsignedTransaction);
-                        case "TRANSACTION_TYPE_SOLANA":
+                        case Chain.Solana:
                             if (!rpcUrl) {
                                 throw new TurnkeyError("Missing rpcUrl: connected Solana wallets require an RPC URL to broadcast transactions.", TurnkeyErrorCodes.SIGN_AND_SEND_TRANSACTION_ERROR);
                             }
-                            if (!walletAccount.signTransaction) {
-                                throw new TurnkeyError("This connected wallet does not support signAndSendTransaction.", TurnkeyErrorCodes.SIGN_AND_SEND_TRANSACTION_ERROR);
-                            }
+                            // not sure why typescript isn't inferring the type here
+                            // if namespace is Chain.Solana, then it must be a ConnectedSolanaWalletAccount
                             const signature = await walletAccount.signTransaction(unsignedTransaction);
                             return await broadcastTransaction({
                                 signedTransaction: signature,
@@ -1710,7 +1848,6 @@ class TurnkeyClient {
         this.addPasskey = async (params) => {
             const { stampWith } = params || {};
             const name = params?.name || `Turnkey Passkey-${Date.now()}`;
-            const displayName = params?.displayName || name;
             return withTurnkeyErrorHandling(async () => {
                 const session = await this.storageManager.getActiveSession();
                 if (!session) {
@@ -1719,7 +1856,6 @@ class TurnkeyClient {
                 const userId = params?.userId || session.userId;
                 const { encodedChallenge, attestation } = await this.createPasskey({
                     name,
-                    displayName,
                     ...(stampWith && { stampWith }),
                 });
                 if (!attestation || !encodedChallenge) {
@@ -2143,11 +2279,7 @@ class TurnkeyClient {
             if (!sessionToken)
                 return;
             withTurnkeyErrorHandling(async () => {
-                const sessionToReplace = await this.storageManager.getSession(sessionKey);
                 await this.storageManager.storeSession(sessionToken, sessionKey);
-                if (sessionToReplace) {
-                    await this.apiKeyStamper?.deleteKeyPair(sessionToReplace.publicKey);
-                }
             }, {
                 errorMessage: "Failed to store session",
                 errorCode: TurnkeyErrorCodes.STORE_SESSION_ERROR,
@@ -2197,9 +2329,8 @@ class TurnkeyClient {
         this.clearAllSessions = async () => {
             withTurnkeyErrorHandling(async () => {
                 const sessionKeys = await this.storageManager.listSessionKeys();
-                if (sessionKeys.length === 0) {
-                    throw new TurnkeyError("No sessions found to clear.", TurnkeyErrorCodes.NO_SESSION_FOUND);
-                }
+                if (sessionKeys.length === 0)
+                    return;
                 for (const sessionKey of sessionKeys) {
                     this.clearSession({ sessionKey });
                 }
@@ -2417,7 +2548,7 @@ class TurnkeyClient {
                 }
                 const publicKey = await this.apiKeyStamper.createKeyPair(externalKeyPair ? externalKeyPair : undefined);
                 if (storeOverride && publicKey) {
-                    await this.apiKeyStamper.setPublicKeyOverride(publicKey);
+                    await this.apiKeyStamper.setTemporaryPublicKey(publicKey);
                 }
                 return publicKey;
             }, {