@turnkey/core 1.0.0-beta.5 → 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 { 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, isWeb, isReactNative, buildSignUpBody, findWalletProviderFromAddress, isEthereumProvider, getPublicKeyFromStampHeader, toExternalTimestamp, isSolanaProvider, getHashFunction, getEncodingType, getEncodedMessage, splitSignature, broadcastTransaction, googleISS, isWalletAccountArray, generateWalletAccountsFromAddressFormat } from '../utils.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);
@@ -372,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) => {
@@ -397,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);
@@ -429,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) {
@@ -452,13 +475,11 @@ class TurnkeyClient {
                             {
                                 apiKeyName: `wallet-auth:${publicKey}`,
                                 publicKey: publicKey,
-                                curveType: isEthereumProvider(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",
                             },
@@ -470,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);
@@ -515,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) => {
@@ -523,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);
@@ -572,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,
@@ -590,9 +619,7 @@ class TurnkeyClient {
                                 {
                                     apiKeyName: `wallet-auth:${publicKey}`,
                                     publicKey: publicKey,
-                                    curveType: isEthereumProvider(walletProvider)
-                                        ? "API_KEY_CURVE_SECP256K1"
-                                        : "API_KEY_CURVE_ED25519",
+                                    curveType: getCurveTypeFromProvider(walletProvider),
                                 },
                             ],
                         },
@@ -602,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,
@@ -625,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);
@@ -734,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) => {
@@ -756,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,
@@ -788,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) => {
@@ -803,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 }),
                 });
@@ -836,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) => {
@@ -852,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",
@@ -886,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) => {
@@ -906,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",
@@ -940,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) => {
@@ -964,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,
@@ -1000,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: {
@@ -1024,6 +1084,7 @@ class TurnkeyClient {
                 return await this.loginWithOauth({
                     oidcToken,
                     publicKey: publicKey,
+                    ...(sessionKey && { sessionKey }),
                 });
             }, {
                 errorMessage: "Failed to sign up with OAuth",
@@ -1040,6 +1101,7 @@ 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.
          */
@@ -1073,6 +1135,8 @@ class TurnkeyClient {
                 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) || [];
@@ -1154,9 +1218,20 @@ 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) {
@@ -1175,6 +1250,7 @@ class TurnkeyClient {
                                 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),
                             };
@@ -1197,6 +1273,7 @@ class TurnkeyClient {
                                 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),
                             };
@@ -1212,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.
          *
@@ -1744,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) {
@@ -1753,7 +1856,6 @@ class TurnkeyClient {
                 const userId = params?.userId || session.userId;
                 const { encodedChallenge, attestation } = await this.createPasskey({
                     name,
-                    displayName,
                     ...(stampWith && { stampWith }),
                 });
                 if (!attestation || !encodedChallenge) {
@@ -2227,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 });
                 }
@@ -2447,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;
             }, {