@getpara/core-sdk 3.4.0 → 3.5.1

package/dist/types/ParaCore.d.ts

@@ -556,7 +556,7 @@ export declare abstract class ParaCore implements CoreInterface {
     protected verifyTelegramProcess(opts: InternalMethodParams<'verifyTelegramLink'> & {
         isLinkAccount: true;
     }): InternalMethodResponse<'verifyTelegramLink'>;
-    verifyTelegram(params: VerifyTelegramParams): Promise<import("./types/authState.js").AuthStateSignupOrLoginOrDone>;
+    verifyTelegram(params: VerifyTelegramParams): Promise<OAuthResponse>;
     protected verifyTelegramLink(opts: InternalMethodParams<'verifyTelegramLink'>): InternalMethodResponse<'verifyTelegramLink'>;
     /**
      * Performs 2FA verification.
@@ -577,6 +577,27 @@ export declare abstract class ParaCore implements CoreInterface {
      * @param {string} opts.verificationCode - the verification code received via 2FA.
      */
     enable2fa({ verificationCode }: CoreMethodParams<'enable2fa'>): CoreMethodResponse<'enable2fa'>;
+    /**
+     * Login-time 2FA (ENG-6906): enroll a TOTP second factor for the current session.
+     * Distinct from setup2fa/enable2fa, which configure the recovery-gating 2FA. This
+     * is authenticated by the active session (no recovery config gate); the backend
+     * 404s the surface when the login-MFA flag is off.
+     *
+     * @returns {Object} `{ uri, backupCodes }` — otpauth URI to render as a QR, plus
+     * one-time backup codes to show the user exactly once.
+     */
+    enrollMfa(): CoreMethodResponse<'enrollMfa'>;
+    /**
+     * Login-time 2FA (ENG-6906): verify the second factor for the current login. On
+     * success the backend stamps the session and this re-polls the login status so the
+     * flow advances toward `done`; a wrong code resolves to `{ ok:false, attemptsRemaining }`
+     * so the UI can re-prompt without treating it as a hard error.
+     *
+     * @param {Object} opts the options object.
+     * @param {string} opts.code the TOTP or backup code entered by the user.
+     * @returns {Object} `{ ok: true } | { ok: false; attemptsRemaining? }`
+     */
+    verifyMfa({ code }: CoreMethodParams<'verifyMfa'>): CoreMethodResponse<'verifyMfa'>;
     /**
      * Resend a verification email for the current user.
      */
@@ -626,7 +647,7 @@ export declare abstract class ParaCore implements CoreInterface {
     protected verifyFarcasterProcess(opts: InternalMethodParams<'verifyFarcasterLink'> & {
         isLinkAccount: true;
     }): InternalMethodResponse<'verifyFarcasterLink'>;
-    verifyFarcaster(params: VerifyFarcasterParams): Promise<import("./types/authState.js").AuthStateSignupOrLoginOrDone>;
+    verifyFarcaster(params: VerifyFarcasterParams): Promise<OAuthResponse>;
     protected verifyFarcasterLink(opts: InternalMethodParams<'verifyFarcasterLink'>): InternalMethodResponse<'verifyFarcasterLink'>;
     /**
      * Generates a URL for the user to log in with OAuth using a desire method.
@@ -823,6 +844,7 @@ export declare abstract class ParaCore implements CoreInterface {
         walletScheme?: TWalletScheme;
     }): Promise<any>;
     private getTransactionReviewUrl;
+    private getDeniedSignatureResultWithUrl;
     private getOnRampTransactionUrl;
     getWalletBalance(params: GetWalletBalanceParams): Promise<string>;
     /**

package/dist/types/errors.d.ts

@@ -10,6 +10,19 @@ export declare class TransactionReviewTimeout extends Error {
     transactionReviewUrl: string;
     constructor(transactionReviewUrl: string, pendingTransactionId: string);
 }
+export interface SigningResultErrorOptions {
+    code?: string;
+    status?: number;
+    responseURL?: string;
+    data?: object;
+}
+export declare class SigningResultError extends Error {
+    readonly code?: string;
+    readonly status?: number;
+    readonly responseURL?: string;
+    readonly data?: object;
+    constructor(message: string, options?: SigningResultErrorOptions);
+}
 /**
  * Discriminant for a `PartnerConfigError`. Each code corresponds to a specific
  * partner-config check that rejected an SDK call. Stable string values are

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 import { ParaCore } from './ParaCore.js';
-export { type Auth, type AuthInfo, type PrimaryAuthInfo, type VerifiedAuthInfo, type VerifiedAuth, AuthMethod, type TAuthMethod, AuthMethodStatus, AuthLayout, type TAuthLayout, type AuthExtras, type CurrentWalletIds, EmailTheme, type PartnerEntity, type PartnerAppConfig, type WalletEntity, Network, type TNetwork, WalletType, type TWalletType, WalletScheme, type TWalletScheme, OnRampAsset, type TOnRampAsset, OnRampPurchaseType, OnRampProvider, OnRampPurchaseStatus, type OnRampConfig, type OnRampAssets, type OnRampPurchase, type OnRampAssetInfo, type ProviderAssetInfo, OnRampMethod, OAuthMethod, type TOAuthMethod, type TLinkedAccountType, type SupportedAccountLinks, type SupportedWalletTypes, type TPregenIdentifierType, type PregenIds, type LinkedAccount, type LinkedAccounts, type TExternalWallet, type ExternalWalletInfo, type PregenAuth, type Setup2faResponse, type TelegramAuthResponse, type VerifyExternalWalletParams, type AssetMetadata, type AssetMetadataIndexed, type AssetValue, type BalancesConfig, type WalletBalance, type ProfileBalance, type OfframpDepositRequest, type WalletWithMetadata, RecoveryStatus, ThemeMode, NON_ED25519, PREGEN_IDENTIFIER_TYPES, WALLET_TYPES, WALLET_SCHEMES, OAUTH_METHODS, LINKED_ACCOUNT_TYPES, EXTERNAL_WALLET_TYPES, EVM_WALLETS, SOLANA_WALLETS, COSMOS_WALLETS, formatAssetQuantity, formatCurrency, type EstimateTransactionOpts, type EstimateTransactionResult, type BroadcastTransactionOpts, type BroadcastTransactionResult, type PendingTransactionEntity, type SerializedDecodedTx, type SerializedTxData, type GetPendingTransactionResponse, DeliveryChannel, type PartnerThemeConfig as Theme, } from '@getpara/user-management-client';
-export { PopupType, PregenIdentifierType, type AuthStateSignup, type AuthStateVerify, type AuthStateLogin, type AuthState, type OAuthResponse, type CoreAuthInfo, type SignatureRes, type FullSignatureRes, type SuccessfulSignatureRes, type DeniedSignatureRes, type DeniedSignatureResWithUrl, type Wallet, type AvailableWallet, type AccountLinkInProgress, AccountLinkError, type InternalInterface, type Verify2faParams, type Verify2faResponse, type StorageType, type TelegramParams, type CreateParaSignerBaseOptions, } from './types/index.js';
+export { type Auth, type AuthInfo, type PrimaryAuthInfo, type VerifiedAuthInfo, type VerifiedAuth, AuthMethod, type TAuthMethod, AuthMethodStatus, AuthLayout, type TAuthLayout, type AuthExtras, type CurrentWalletIds, EmailTheme, type PartnerEntity, type PartnerAppConfig, type WalletEntity, Network, type TNetwork, WalletType, type TWalletType, WalletScheme, type TWalletScheme, OnRampAsset, type TOnRampAsset, OnRampPurchaseType, OnRampProvider, OnRampPurchaseStatus, type OnRampConfig, type OnRampAssets, type OnRampPurchase, type OnRampAssetInfo, type ProviderAssetInfo, OnRampMethod, OAuthMethod, type TOAuthMethod, type TLinkedAccountType, type SupportedAccountLinks, type SupportedWalletTypes, type TPregenIdentifierType, type PregenIds, type LinkedAccount, type LinkedAccounts, type TExternalWallet, type ExternalWalletInfo, type PregenAuth, type Setup2faResponse, type EnrollMfaResponse, type VerifyMfaResult, type MfaChallenge, type MfaMode, type MfaStep, type TelegramAuthResponse, type VerifyExternalWalletParams, type AssetMetadata, type AssetMetadataIndexed, type AssetValue, type BalancesConfig, type WalletBalance, type ProfileBalance, type OfframpDepositRequest, type WalletWithMetadata, RecoveryStatus, ThemeMode, NON_ED25519, PREGEN_IDENTIFIER_TYPES, WALLET_TYPES, WALLET_SCHEMES, OAUTH_METHODS, LINKED_ACCOUNT_TYPES, EXTERNAL_WALLET_TYPES, EVM_WALLETS, SOLANA_WALLETS, COSMOS_WALLETS, formatAssetQuantity, formatCurrency, type EstimateTransactionOpts, type EstimateTransactionResult, type BroadcastTransactionOpts, type BroadcastTransactionResult, type PendingTransactionEntity, type SerializedDecodedTx, type SerializedTxData, type GetPendingTransactionResponse, DeliveryChannel, type PartnerThemeConfig as Theme, } from '@getpara/user-management-client';
+export { PopupType, PregenIdentifierType, type AuthStateSignup, type AuthStateVerify, type AuthStateLogin, type AuthState, type OAuthResponse, type CoreAuthInfo, type SignatureRes, type FullSignatureRes, type SuccessfulSignatureRes, type DeniedSignatureRes, type DeniedSignatureResWithUrl, type Wallet, type AvailableWallet, type AccountLinkInProgress, AccountLinkError, type InternalInterface, type Verify2faParams, type Verify2faResponse, type VerifyMfaParams, type AuthStateMfa, type StorageType, type TelegramParams, type CreateParaSignerBaseOptions, } from './types/index.js';
 export * from './types/smartAccounts.js';
 export * from './types/coreApi.js';
 export * from './types/events.js';

package/dist/types/services/AuthService.d.ts

@@ -9,7 +9,7 @@ import { WalletService } from './WalletService.js';
 import type { WaitForLoginMethod } from './types/LoginFlowServiceTypes';
 import type { WaitForSignupMethod, WaitForWalletCreationMethod } from './types/SignupFlowServiceTypes';
 import { PerformVerifyExternalWalletMethod, PerformVerifyFarcasterMethod, PerformVerifyNewAccountMethod, PerformVerifyTelegramMethod, RetryVerifyExternalWalletMethod, VerifyExternalWalletMethod, VerifyFarcasterMethod, VerifyNewAccountMethod, VerifyTelegramMethod } from './types/VerificationFlowServiceTypes.js';
-import type { AddCredentialMethod, AssertIsAuthSetMethod, AssertUserIdMethod, AuthenticateWithEmailOrPhoneMethod, AuthenticateWithOAuthMethod, ConnectExternalWalletMethod, GetNewCredentialAndUrlMethod, LoginExternalWalletMethod, PerformLoginExternalWalletMethod, PerformSignUpOrLogInMethod, PrepareAuthStateMethod, PrepareLoginStateMethod, ResendVerificationCodeMethod, SetAuthMethod, SignExternalWalletVerificationMethod, SignUpOrLogInMethod, SupportedUserAuthMethodsMethod, VerifyOAuthProcessMethod } from './types/AuthServiceTypes.js';
+import type { AddCredentialMethod, AssertIsAuthSetMethod, AssertUserIdMethod, AuthenticateWithEmailOrPhoneMethod, AuthenticateWithOAuthMethod, ConnectExternalWalletMethod, EnrollMfaMethod, GetNewCredentialAndUrlMethod, LoginExternalWalletMethod, PerformLoginExternalWalletMethod, PerformSignUpOrLogInMethod, PrepareAuthStateMethod, PrepareLoginStateMethod, ResendVerificationCodeMethod, ResolveMfaMethod, VerifyMfaMethod, SetAuthMethod, SignExternalWalletVerificationMethod, SignUpOrLogInMethod, SupportedUserAuthMethodsMethod, VerifyOAuthProcessMethod } from './types/AuthServiceTypes.js';
 export declare class AuthService {
     #private;
     userId?: string;
@@ -60,6 +60,15 @@ export declare class AuthService {
     connectExternalWallet: ConnectExternalWalletMethod;
     signExternalWalletVerification: SignExternalWalletVerificationMethod;
     verifyOAuthProcess: VerifyOAuthProcessMethod;
+    /**
+     * Login-time 2FA (ENG-6906): after the second factor has been satisfied/enrolled
+     * server-side, re-poll the login status to advance the flow. Fires RESOLVE_2FA,
+     * which re-enters verify-oauth polling (now returning stage:'done') and routes
+     * onward to awaiting_session_start / authenticated.
+     */
+    resolveMfa: ResolveMfaMethod;
+    enrollMfa: EnrollMfaMethod;
+    verifyMfa: VerifyMfaMethod;
     authenticateWithOAuth: AuthenticateWithOAuthMethod;
     performVerifyTelegram: PerformVerifyTelegramMethod;
     verifyTelegram: VerifyTelegramMethod;

package/dist/types/services/types/AuthServiceTypes.d.ts

@@ -1,5 +1,5 @@
-import type { Auth, AuthExtras, AuthMethod, AuthType, DeliveryChannel, ExternalWalletInfo, PrimaryAuth, PrimaryAuthInfo, ServerAuthState, ServerAuthStateLogin, TAuthMethod, PartnerThemeConfig, TOAuthMethod } from '@getpara/user-management-client';
-import type { AuthState, AuthStateDone, AuthStateLogin, AuthStateSignup, AuthStateVerify, CoreAuthInfo, WithCustomTheme, WithSessionLookupId, WithShorten, WithUseShortUrls } from '../../types/index.js';
+import type { Auth, AuthExtras, AuthMethod, AuthType, DeliveryChannel, EnrollMfaResponse, ExternalWalletInfo, PrimaryAuth, PrimaryAuthInfo, ServerAuthState, ServerAuthStateLogin, TAuthMethod, PartnerThemeConfig, TOAuthMethod, VerifyMfaResult } from '@getpara/user-management-client';
+import type { AuthState, AuthStateDone, AuthStateLogin, AuthStateMfa, AuthStateSignup, AuthStateVerify, CoreAuthInfo, VerifyMfaParams, WithCustomTheme, WithSessionLookupId, WithShorten, WithUseShortUrls } from '../../types/index.js';
 import type { InitOAuthPollingParams, PollingCallbacks } from './PollingServiceTypes.js';
 import { PerformConnectExternalWalletResponse, ExternalSignMessageParams } from './ExternalWalletServiceTypes.js';
 import { BaseVerifyExternalWalletParams } from './VerificationFlowServiceTypes.js';
@@ -96,8 +96,11 @@ interface PerformLoginExternalWalletResponse {
 export type PerformLoginExternalWalletMethod = (_: LoginExternalWalletParams) => Promise<PerformLoginExternalWalletResponse>;
 export interface VerifyOAuthProcessParams extends PollingCallbacks, InitOAuthPollingParams {
 }
-export type VerifyOAuthProcessResponse = AuthStateLogin | AuthStateSignup | AuthStateDone;
+export type VerifyOAuthProcessResponse = AuthStateLogin | AuthStateSignup | AuthStateDone | AuthStateMfa;
 export type VerifyOAuthProcessMethod = (_: VerifyOAuthProcessParams) => Promise<VerifyOAuthProcessResponse>;
+export type EnrollMfaMethod = () => Promise<EnrollMfaResponse>;
+export type VerifyMfaMethod = (_: VerifyMfaParams) => Promise<VerifyMfaResult>;
+export type ResolveMfaMethod = (_?: PollingCallbacks) => Promise<AuthState>;
 export interface AuthenticateWithOAuthParams extends WithCustomTheme, WithUseShortUrls {
     /**
      * The third-party OAuth service.

package/dist/types/state/CoreStateManager.d.ts

@@ -33,4 +33,5 @@ export declare class CoreStateManager {
     private notifyListeners;
     private statesEqual;
     private authStateInfoEqual;
+    private mfaEqual;
 }

package/dist/types/state/machines/authStateMachine.d.ts

@@ -216,7 +216,7 @@ export declare function createAuthStateMachine(paraCoreInterface: StateMachineIn
         type: "canRetryNewAccount";
         params: unknown;
     };
-}>, never, "error" | "checking_state" | "clearing_state" | "unauthenticated" | "authenticating_email_phone" | "authenticating_oauth" | "connecting_external_wallet" | "switching_external_wallet" | "authenticating_external_wallet" | "authenticating_telegram" | "authenticating_telegram_legacy" | "authenticating_farcaster" | "authenticating_farcaster_legacy" | "waiting_for_farcaster" | "processing_authentication" | "awaiting_wallet_signature" | "awaiting_wallet_verification" | "awaiting_account_verification" | "awaiting_session_start" | "verifying_new_account" | "verifying_external_wallet" | "waiting_for_session" | "authenticated" | "guest_mode" | "signing_external_wallet_verification", string, AuthInput, {}, import("xstate").EventObject, import("xstate").MetaObject, {
+}>, never, "error" | "checking_state" | "clearing_state" | "unauthenticated" | "authenticating_email_phone" | "authenticating_oauth" | "connecting_external_wallet" | "switching_external_wallet" | "authenticating_external_wallet" | "authenticating_telegram" | "authenticating_telegram_legacy" | "authenticating_farcaster" | "authenticating_farcaster_legacy" | "waiting_for_farcaster" | "processing_authentication" | "awaiting_wallet_signature" | "awaiting_wallet_verification" | "awaiting_account_verification" | "awaiting_2fa" | "awaiting_2fa_enrollment" | "resolving_2fa" | "awaiting_session_start" | "verifying_new_account" | "verifying_external_wallet" | "waiting_for_session" | "authenticated" | "guest_mode" | "signing_external_wallet_verification", string, AuthInput, {}, import("xstate").EventObject, import("xstate").MetaObject, {
     readonly id: "auth";
     readonly initial: "checking_state";
     readonly context: ({ input: { coreRef } }: {
@@ -2041,6 +2041,26 @@ export declare function createAuthStateMachine(paraCoreInterface: StateMachineIn
                         };
                     }];
                     readonly guard: import("xstate/dist/declarations/src/guards.js").GuardPredicate<AuthContext, import("xstate").DoneActorEvent<AuthState, string>, unknown, never>;
+                }, {
+                    readonly target: "awaiting_2fa_enrollment";
+                    readonly actions: readonly ["storeAuthStateResult", {
+                        readonly type: "logTransition";
+                        readonly params: {
+                            readonly to: "awaiting_2fa_enrollment";
+                            readonly detail: "mfa enroll";
+                        };
+                    }];
+                    readonly guard: ({ event }: import("xstate/dist/declarations/src/guards.js").GuardArgs<AuthContext, import("xstate").DoneActorEvent<AuthState, string>>) => boolean;
+                }, {
+                    readonly target: "awaiting_2fa";
+                    readonly actions: readonly ["storeAuthStateResult", {
+                        readonly type: "logTransition";
+                        readonly params: {
+                            readonly to: "awaiting_2fa";
+                            readonly detail: "mfa verify";
+                        };
+                    }];
+                    readonly guard: ({ event }: import("xstate/dist/declarations/src/guards.js").GuardArgs<AuthContext, import("xstate").DoneActorEvent<AuthState, string>>) => boolean;
                 }, {
                     readonly target: "awaiting_session_start";
                     readonly actions: readonly ["storeAuthStateResult", {
@@ -2100,6 +2120,62 @@ export declare function createAuthStateMachine(paraCoreInterface: StateMachineIn
                 };
             };
         };
+        readonly awaiting_2fa: {
+            readonly on: {
+                readonly RESOLVE_2FA: {
+                    readonly target: "resolving_2fa";
+                    readonly actions: readonly ["setPollingCallbacks", "resetError"];
+                };
+                readonly CANCEL: {
+                    readonly target: "unauthenticated";
+                    readonly actions: readonly ["resetState"];
+                };
+            };
+        };
+        readonly awaiting_2fa_enrollment: {
+            readonly on: {
+                readonly RESOLVE_2FA: {
+                    readonly target: "resolving_2fa";
+                    readonly actions: readonly ["setPollingCallbacks", "resetError"];
+                };
+                readonly CANCEL: {
+                    readonly target: "unauthenticated";
+                    readonly actions: readonly ["resetState"];
+                };
+            };
+        };
+        readonly resolving_2fa: {
+            readonly entry: readonly [{
+                readonly type: "logTransition";
+                readonly params: {
+                    readonly to: "resolving_2fa";
+                };
+            }];
+            readonly invoke: {
+                readonly src: "polling";
+                readonly input: ({ context }: {
+                    context: AuthContext;
+                    event: AuthEvents;
+                    self: import("xstate").ActorRef<import("xstate").MachineSnapshot<AuthContext, AuthEvents, Record<string, import("xstate").AnyActorRef>, import("xstate").StateValue, string, unknown, any, any>, AuthEvents, import("xstate").AnyEventObject>;
+                }) => {
+                    checkCondition: () => Promise<{
+                        finished: boolean;
+                        data: {
+                            authState: ServerAuthState;
+                        };
+                    }>;
+                    onPoll: () => void;
+                    onCancel: () => void;
+                    isCanceled: () => boolean;
+                    id: string;
+                };
+                readonly onError: {
+                    readonly target: "error";
+                    readonly actions: any;
+                };
+            };
+            readonly on: any;
+        };
         readonly awaiting_session_start: {
             readonly on: {
                 readonly WAIT_FOR_SESSION: {