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

package/dist/__clients__/core.js

@@ -23,9 +23,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.
@@ -33,16 +33,16 @@ class TurnkeyClient {
          */
         this.createPasskey = async (params) => {
             return utils.withTurnkeyErrorHandling(async () => {
-                const name = params?.name || "A Passkey";
-                const displayName = params?.displayName || "A Passkey";
+                const name = utils.isValidPasskeyName(params?.name || `passkey-${Date.now()}`);
                 let passkey;
                 if (utils.isWeb()) {
                     const res = await this.passkeyStamper?.createWebPasskey({
                         publicKey: {
                             user: {
                                 name,
-                                displayName,
+                                displayName: name,
                             },
+                            ...(params?.challenge && { challenge: params.challenge }),
                         },
                     });
                     if (!res) {
@@ -56,7 +56,7 @@ class TurnkeyClient {
                 else if (utils.isReactNative()) {
                     const res = await this.passkeyStamper?.createReactNativePasskey({
                         name,
-                        displayName,
+                        displayName: name,
                     });
                     if (!res) {
                         throw new sdkTypes.TurnkeyError("Failed to create React Native passkey", sdkTypes.TurnkeyErrorCodes.INTERNAL_ERROR);
@@ -127,21 +127,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 utils.withTurnkeyErrorHandling(async () => {
-                generatedKeyPair =
+                generatedPublicKey =
                     params?.publicKey || (await this.apiKeyStamper?.createKeyPair());
                 const sessionKey = params?.sessionKey || base.SessionKey.DefaultSessionkey;
                 const expirationSeconds = params?.expirationSeconds || base.DEFAULT_SESSION_EXPIRATION_IN_SECONDS;
-                if (!generatedKeyPair) {
+                if (!generatedPublicKey) {
                     throw new sdkTypes.TurnkeyError("A publickey could not be found or generated.", sdkTypes.TurnkeyErrorCodes.INTERNAL_ERROR);
                 }
                 const sessionResponse = await this.httpClient.stampLogin({
-                    publicKey: generatedKeyPair,
+                    publicKey: generatedPublicKey,
                     organizationId: this.config.organizationId,
                     expirationSeconds,
                 }, base.StamperType.Passkey);
@@ -149,8 +151,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: sdkTypes.TurnkeyErrorCodes.PASSKEY_LOGIN_AUTH_ERROR,
@@ -162,9 +170,9 @@ class TurnkeyClient {
                 },
             }, {
                 finallyFn: async () => {
-                    if (generatedKeyPair) {
+                    if (generatedPublicKey) {
                         try {
-                            await this.apiKeyStamper?.deleteKeyPair(generatedKeyPair);
+                            await this.apiKeyStamper?.deleteKeyPair(generatedPublicKey);
                         }
                         catch (cleanupError) {
                             throw new sdkTypes.TurnkeyError(`Failed to clean up generated key pair`, sdkTypes.TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
@@ -182,23 +190,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 = base.SessionKey.DefaultSessionkey, expirationSeconds = base.DEFAULT_SESSION_EXPIRATION_IN_SECONDS, } = params || {};
-            let generatedKeyPair = undefined;
+            let generatedPublicKey = undefined;
             return utils.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 sdkTypes.TurnkeyError("Failed to create passkey: encoded challenge or attestation is missing", sdkTypes.TurnkeyErrorCodes.INTERNAL_ERROR);
@@ -217,8 +228,8 @@ class TurnkeyClient {
                         ],
                         apiKeys: [
                             {
-                                apiKeyName: `passkey-auth-${generatedKeyPair}`,
-                                publicKey: generatedKeyPair,
+                                apiKeyName: `passkey-auth-${generatedPublicKey}`,
+                                publicKey: generatedPublicKey,
                                 curveType: "API_KEY_CURVE_P256",
                                 expirationSeconds: "60",
                             },
@@ -230,28 +241,31 @@ class TurnkeyClient {
                     throw new sdkTypes.TurnkeyError(`Sign up failed`, sdkTypes.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: sdkTypes.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 sdkTypes.TurnkeyError(`Failed to clean up generated key pair`, sdkTypes.TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
@@ -374,7 +388,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) => {
@@ -399,14 +415,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: utils.addressFromPublicKey(walletProvider.chainInfo.namespace, publicKey),
+                };
             }, {
                 errorMessage: "Unable to log in with the provided wallet",
                 errorCode: sdkTypes.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);
@@ -431,17 +452,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 = base.SessionKey.DefaultSessionkey, expirationSeconds = base.DEFAULT_SESSION_EXPIRATION_IN_SECONDS, } = params;
-            let generatedKeyPair = undefined;
+            let generatedPublicKey = undefined;
             return utils.withTurnkeyErrorHandling(async () => {
                 if (!this.walletManager?.stamper) {
                     throw new sdkTypes.TurnkeyError("Wallet stamper is not initialized", sdkTypes.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) {
@@ -454,13 +477,11 @@ class TurnkeyClient {
                             {
                                 apiKeyName: `wallet-auth:${publicKey}`,
                                 publicKey: publicKey,
-                                curveType: utils.isEthereumProvider(walletProvider)
-                                    ? "API_KEY_CURVE_SECP256K1"
-                                    : "API_KEY_CURVE_ED25519",
+                                curveType: utils.getCurveTypeFromProvider(walletProvider),
                             },
                             {
-                                apiKeyName: `wallet-auth-${generatedKeyPair}`,
-                                publicKey: generatedKeyPair,
+                                apiKeyName: `wallet-auth-${generatedPublicKey}`,
+                                publicKey: generatedPublicKey,
                                 curveType: "API_KEY_CURVE_P256",
                                 expirationSeconds: "60",
                             },
@@ -472,29 +493,34 @@ class TurnkeyClient {
                     throw new sdkTypes.TurnkeyError(`Sign up failed`, sdkTypes.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: utils.addressFromPublicKey(walletProvider.chainInfo.namespace, publicKey),
+                };
             }, {
                 errorMessage: "Failed to sign up with wallet",
                 errorCode: sdkTypes.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 sdkTypes.TurnkeyError("Failed to clean up generated key pair", sdkTypes.TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
@@ -517,7 +543,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) => {
@@ -525,19 +554,19 @@ class TurnkeyClient {
             const sessionKey = params.sessionKey || base.SessionKey.DefaultSessionkey;
             const walletProvider = params.walletProvider;
             const expirationSeconds = params.expirationSeconds || base.DEFAULT_SESSION_EXPIRATION_IN_SECONDS;
-            let generatedKeyPair = undefined;
+            let generatedPublicKey = undefined;
             return utils.withTurnkeyErrorHandling(async () => {
                 if (!this.walletManager?.stamper) {
                     throw new sdkTypes.TurnkeyError("Wallet stamper is not initialized", sdkTypes.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 utils.withTurnkeyErrorHandling(async () => {
                     return this.httpClient.stampStampLogin({
-                        publicKey: generatedKeyPair,
+                        publicKey: generatedPublicKey,
                         organizationId: this.config.organizationId,
                         expirationSeconds,
                     }, base.StamperType.Wallet);
@@ -574,7 +603,7 @@ class TurnkeyClient {
                         throw new sdkTypes.TurnkeyError(`Unsupported interface type: ${walletProvider.interfaceType}`, sdkTypes.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: base.FilterType.PublicKey,
                     filterValue: publicKey,
@@ -592,9 +621,7 @@ class TurnkeyClient {
                                 {
                                     apiKeyName: `wallet-auth:${publicKey}`,
                                     publicKey: publicKey,
-                                    curveType: utils.isEthereumProvider(walletProvider)
-                                        ? "API_KEY_CURVE_SECP256K1"
-                                        : "API_KEY_CURVE_ED25519",
+                                    curveType: utils.getCurveTypeFromProvider(walletProvider),
                                 },
                             ],
                         },
@@ -604,7 +631,7 @@ class TurnkeyClient {
                         throw new sdkTypes.TurnkeyError(`Sign up failed`, sdkTypes.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,
@@ -627,14 +654,19 @@ class TurnkeyClient {
                     sessionToken: sessionToken,
                     sessionKey,
                 });
-                return sessionToken;
+                return {
+                    sessionToken: sessionToken,
+                    address: utils.addressFromPublicKey(walletProvider.chainInfo.namespace, publicKey),
+                    // if the subOrganizationId exists, it means the user is logging in
+                    action: subOrganizationId ? sdkTypes.AuthAction.LOGIN : sdkTypes.AuthAction.SIGNUP,
+                };
             }, {
                 errorCode: sdkTypes.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 sdkTypes.TurnkeyError(`Failed to clean up generated key pair`, sdkTypes.TurnkeyErrorCodes.KEY_PAIR_CLEANUP_ERROR, cleanupError);
@@ -736,7 +768,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) => {
@@ -758,7 +791,9 @@ class TurnkeyClient {
                     sessionToken: loginRes.session,
                     sessionKey,
                 });
-                return loginRes.session;
+                return {
+                    sessionToken: loginRes.session,
+                };
             }, {
                 errorMessage: "Failed to log in with OTP",
                 errorCode: sdkTypes.TurnkeyErrorCodes.OTP_LOGIN_ERROR,
@@ -790,7 +825,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) => {
@@ -805,14 +841,14 @@ class TurnkeyClient {
                 },
             });
             return utils.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 sdkTypes.TurnkeyError(`Auth proxy OTP sign up failed`, sdkTypes.TurnkeyErrorCodes.OTP_SIGNUP_ERROR);
                 }
                 return await this.loginWithOtp({
                     verificationToken,
-                    publicKey: generatedKeyPair,
+                    publicKey: generatedPublicKey,
                     ...(invalidateExisting && { invalidateExisting }),
                     ...(sessionKey && { sessionKey }),
                 });
@@ -838,7 +874,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) => {
@@ -854,24 +893,32 @@ class TurnkeyClient {
                     throw new sdkTypes.TurnkeyError("No verification token returned from OTP verification", sdkTypes.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: sdkTypes.AuthAction.SIGNUP,
+                    };
                 }
                 else {
-                    return await this.loginWithOtp({
+                    const loginRes = await this.loginWithOtp({
                         verificationToken,
                         ...(publicKey && { publicKey }),
                         ...(invalidateExisting && { invalidateExisting }),
                         ...(sessionKey && { sessionKey }),
                     });
+                    return {
+                        ...loginRes,
+                        verificationToken,
+                        action: sdkTypes.AuthAction.LOGIN,
+                    };
                 }
             }, {
                 errorMessage: "Failed to complete OTP process",
@@ -888,12 +935,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) => {
@@ -908,22 +957,31 @@ class TurnkeyClient {
                 }
                 const subOrganizationId = accountRes.organizationId;
                 if (subOrganizationId) {
-                    return this.loginWithOauth({
+                    const loginRes = await this.loginWithOauth({
                         oidcToken,
                         publicKey,
                         invalidateExisting,
                         sessionKey,
                     });
+                    return {
+                        ...loginRes,
+                        action: sdkTypes.AuthAction.LOGIN,
+                    };
                 }
                 else {
-                    return this.signUpWithOauth({
+                    const signUpRes = await this.signUpWithOauth({
                         oidcToken,
                         publicKey,
                         providerName,
+                        sessionKey,
                         ...(createSubOrgParams && {
                             createSubOrgParams,
                         }),
                     });
+                    return {
+                        ...signUpRes,
+                        action: sdkTypes.AuthAction.SIGNUP,
+                    };
                 }
             }, {
                 errorMessage: "Failed to complete OAuth process",
@@ -942,7 +1000,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) => {
@@ -966,7 +1025,7 @@ class TurnkeyClient {
                     sessionToken: loginRes.session,
                     sessionKey,
                 });
-                return loginRes.session;
+                return { sessionToken: loginRes.session };
             }, {
                 errorMessage: "Failed to complete OAuth login",
                 errorCode: sdkTypes.TurnkeyErrorCodes.OAUTH_LOGIN_ERROR,
@@ -1002,11 +1061,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 utils.withTurnkeyErrorHandling(async () => {
                 const signUpBody = utils.buildSignUpBody({
                     createSubOrgParams: {
@@ -1026,6 +1086,7 @@ class TurnkeyClient {
                 return await this.loginWithOauth({
                     oidcToken,
                     publicKey: publicKey,
+                    ...(sessionKey && { sessionKey }),
                 });
             }, {
                 errorMessage: "Failed to sign up with OAuth",
@@ -1042,6 +1103,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.
          */
@@ -1075,6 +1137,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) || [];
@@ -1156,9 +1220,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 } = utils.getAuthenticatorAddresses(user);
                 for (const provider of matching) {
                     const timestamp = utils.toExternalTimestamp();
                     for (const address of provider.connectedAddresses) {
@@ -1177,6 +1252,7 @@ class TurnkeyClient {
                                 curve: base.Curve.SECP256K1,
                                 addressFormat: "ADDRESS_FORMAT_ETHEREUM",
                                 chainInfo: provider.chainInfo,
+                                isAuthenticator: ethereumAddresses.includes(address.toLowerCase()),
                                 signMessage: (msg) => sign(msg, provider, base.SignIntent.SignMessage),
                                 signAndSendTransaction: (tx) => sign(tx, provider, base.SignIntent.SignAndSendTransaction),
                             };
@@ -1199,6 +1275,7 @@ class TurnkeyClient {
                                 curve: base.Curve.ED25519,
                                 addressFormat: "ADDRESS_FORMAT_SOLANA",
                                 chainInfo: provider.chainInfo,
+                                isAuthenticator: solanaAddresses.includes(address),
                                 signMessage: (msg) => sign(msg, provider, base.SignIntent.SignMessage),
                                 signTransaction: (tx) => sign(tx, provider, base.SignIntent.SignTransaction),
                             };
@@ -1214,6 +1291,33 @@ class TurnkeyClient {
                 errorCode: sdkTypes.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 sdkTypes.TurnkeyError("No active session found. Please log in first.", sdkTypes.TurnkeyErrorCodes.NO_SESSION_FOUND);
+            }
+            return utils.withTurnkeyErrorHandling(async () => {
+                const res = await this.httpClient.getPrivateKeys({ organizationId: session.organizationId }, stampWith);
+                if (!res) {
+                    throw new sdkTypes.TurnkeyError("Failed to fetch private keys", sdkTypes.TurnkeyErrorCodes.BAD_RESPONSE);
+                }
+                return res.privateKeys;
+            }, {
+                errorMessage: "Failed to fetch private keys",
+                errorCode: sdkTypes.TurnkeyErrorCodes.FETCH_PRIVATE_KEYS_ERROR,
+            });
+        };
         /**
          * Signs a message using the specified wallet account.
          *
@@ -1746,7 +1850,6 @@ class TurnkeyClient {
         this.addPasskey = async (params) => {
             const { stampWith } = params || {};
             const name = params?.name || `Turnkey Passkey-${Date.now()}`;
-            const displayName = params?.displayName || name;
             return utils.withTurnkeyErrorHandling(async () => {
                 const session = await this.storageManager.getActiveSession();
                 if (!session) {
@@ -1755,7 +1858,6 @@ class TurnkeyClient {
                 const userId = params?.userId || session.userId;
                 const { encodedChallenge, attestation } = await this.createPasskey({
                     name,
-                    displayName,
                     ...(stampWith && { stampWith }),
                 });
                 if (!attestation || !encodedChallenge) {
@@ -2229,9 +2331,8 @@ class TurnkeyClient {
         this.clearAllSessions = async () => {
             utils.withTurnkeyErrorHandling(async () => {
                 const sessionKeys = await this.storageManager.listSessionKeys();
-                if (sessionKeys.length === 0) {
-                    throw new sdkTypes.TurnkeyError("No sessions found to clear.", sdkTypes.TurnkeyErrorCodes.NO_SESSION_FOUND);
-                }
+                if (sessionKeys.length === 0)
+                    return;
                 for (const sessionKey of sessionKeys) {
                     this.clearSession({ sessionKey });
                 }
@@ -2449,7 +2550,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;
             }, {