@getpara/core-sdk 3.4.0 → 3.5.1

package/dist/cjs/ParaCore.js

@@ -124,6 +124,24 @@ if (typeof global !== "undefined") {
   self.global = self.global || self;
 }
 const { pki, jsbn } = import_node_forge.default;
+const DEFAULT_SIGNING_RESULT_ERROR_MESSAGE = "Signing failed before a signature was produced.";
+function getPendingTransactionId(signRes) {
+  return typeof signRes.pendingTransactionId === "string" && signRes.pendingTransactionId.length > 0 ? signRes.pendingTransactionId : void 0;
+}
+function requireSuccessfulSignatureResult(signRes) {
+  if (typeof signRes.signature === "string" && signRes.signature.length > 0) {
+    return { signature: signRes.signature };
+  }
+  throw new import_errors.SigningResultError(
+    typeof signRes.message === "string" && signRes.message.length > 0 ? signRes.message : DEFAULT_SIGNING_RESULT_ERROR_MESSAGE,
+    {
+      code: signRes.code,
+      status: signRes.status,
+      responseURL: signRes.responseURL,
+      data: signRes.data
+    }
+  );
+}
 const _ParaCore = class _ParaCore {
   constructor(envOrApiKey, apiKeyOrOpts, opts) {
     __privateAdd(this, _ParaCore_instances);
@@ -1825,6 +1843,37 @@ const _ParaCore = class _ParaCore {
       yield this.ctx.client.enable2FA(userId, verificationCode);
     });
   }
+  /**
+   * 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() {
+    return __async(this, null, function* () {
+      yield __privateMethod(this, _ParaCore_instances, assertPartner_fn).call(this);
+      return yield __privateGet(this, _authService).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(_0) {
+    return __async(this, arguments, function* ({ code }) {
+      yield __privateMethod(this, _ParaCore_instances, assertPartner_fn).call(this);
+      return yield __privateGet(this, _authService).verifyMfa({ code });
+    });
+  }
   /**
    * Resend a verification email for the current user.
    */
@@ -2386,6 +2435,14 @@ const _ParaCore = class _ParaCore {
       return result.url;
     });
   }
+  getDeniedSignatureResultWithUrl(pendingTransactionId) {
+    return __async(this, null, function* () {
+      return {
+        pendingTransactionId,
+        transactionReviewUrl: yield this.getTransactionReviewUrl(pendingTransactionId)
+      };
+    });
+  }
   getOnRampTransactionUrl(_0) {
     return __async(this, arguments, function* ({
       purchaseId
@@ -2448,11 +2505,9 @@ const _ParaCore = class _ParaCore {
       );
       let timeStart = Date.now();
       const effectiveTimeoutMs = Math.max(timeoutMs, constants.TRANSACTION_REVIEW_TIMEOUT_MS);
-      if (signRes.pendingTransactionId) {
-        const reviewUrl = yield this.getTransactionReviewUrl(
-          signRes.pendingTransactionId,
-          effectiveTimeoutMs
-        );
+      let pendingTransactionId = getPendingTransactionId(signRes);
+      if (pendingTransactionId) {
+        const reviewUrl = yield this.getTransactionReviewUrl(pendingTransactionId, effectiveTimeoutMs);
         if (onTransactionReviewUrl) {
           onTransactionReviewUrl(reviewUrl);
         } else {
@@ -2461,8 +2516,9 @@ const _ParaCore = class _ParaCore {
           });
         }
       } else {
-        (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_MESSAGE_EVENT, signRes);
-        return signRes;
+        const successfulSignRes2 = requireSuccessfulSignatureResult(signRes);
+        (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_MESSAGE_EVENT, successfulSignRes2);
+        return successfulSignRes2;
       }
       while (true) {
         if (isCanceled() || Date.now() - timeStart > effectiveTimeoutMs) {
@@ -2476,15 +2532,19 @@ const _ParaCore = class _ParaCore {
             "tx.review.poll",
             (span) => __async(this, null, function* () {
               var _a;
-              const res = (_a = (yield this.ctx.client.getPendingTransaction(this.userId, signRes.pendingTransactionId)).data) == null ? void 0 : _a.pendingTransaction;
+              const res = (_a = (yield this.ctx.client.getPendingTransaction(this.userId, pendingTransactionId)).data) == null ? void 0 : _a.pendingTransaction;
               span.setAttribute("polling.status", (res == null ? void 0 : res.approvedAt) ? "approved" : "pending");
               return res;
             }),
-            { "pending_transaction.id": signRes.pendingTransactionId }
+            { "pending_transaction.id": pendingTransactionId }
           );
         } catch (e) {
           const error = new import_errors.TransactionReviewDenied();
-          (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_MESSAGE_EVENT, signRes, error.message);
+          (0, import_utils2.dispatchEvent)(
+            import_types.ParaEvent.SIGN_MESSAGE_EVENT,
+            yield this.getDeniedSignatureResultWithUrl(pendingTransactionId),
+            error.message
+          );
           throw error;
         }
         if (!(pendingTransaction == null ? void 0 : pendingTransaction.approvedAt)) {
@@ -2499,16 +2559,16 @@ const _ParaCore = class _ParaCore {
           break;
         }
       }
-      if (signRes.pendingTransactionId) {
-        const error = new import_errors.TransactionReviewTimeout(
-          yield this.getTransactionReviewUrl(signRes.pendingTransactionId),
-          signRes.pendingTransactionId
-        );
-        (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_MESSAGE_EVENT, signRes, error.message);
+      pendingTransactionId = getPendingTransactionId(signRes);
+      if (pendingTransactionId) {
+        const deniedSignRes = yield this.getDeniedSignatureResultWithUrl(pendingTransactionId);
+        const error = new import_errors.TransactionReviewTimeout(deniedSignRes.transactionReviewUrl, pendingTransactionId);
+        (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_MESSAGE_EVENT, deniedSignRes, error.message);
         throw error;
       }
-      (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_MESSAGE_EVENT, signRes);
-      return signRes;
+      const successfulSignRes = requireSuccessfulSignatureResult(signRes);
+      (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_MESSAGE_EVENT, successfulSignRes);
+      return successfulSignRes;
     });
   }
   signMessageInner(_0) {
@@ -2587,19 +2647,18 @@ const _ParaCore = class _ParaCore {
       );
       let timeStart = Date.now();
       const effectiveTimeoutMs = Math.max(timeoutMs, constants.TRANSACTION_REVIEW_TIMEOUT_MS);
-      if (signRes.pendingTransactionId) {
-        const reviewUrl = yield this.getTransactionReviewUrl(
-          signRes.pendingTransactionId,
-          effectiveTimeoutMs
-        );
+      let pendingTransactionId = getPendingTransactionId(signRes);
+      if (pendingTransactionId) {
+        const reviewUrl = yield this.getTransactionReviewUrl(pendingTransactionId, effectiveTimeoutMs);
         if (onTransactionReviewUrl) {
           onTransactionReviewUrl(reviewUrl);
         } else {
           yield this.platformUtils.openPopup(reviewUrl, { type: import_types.PopupType.SIGN_TRANSACTION_REVIEW });
         }
       } else {
-        (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_TRANSACTION_EVENT, signRes);
-        return signRes;
+        const successfulSignRes2 = requireSuccessfulSignatureResult(signRes);
+        (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_TRANSACTION_EVENT, successfulSignRes2);
+        return successfulSignRes2;
       }
       while (true) {
         if (isCanceled() || Date.now() - timeStart > effectiveTimeoutMs) {
@@ -2607,7 +2666,7 @@ const _ParaCore = class _ParaCore {
           break;
         }
         yield new Promise((resolve) => setTimeout(resolve, constants.POLLING_INTERVAL_MS));
-        const pendingTxId = signRes.pendingTransactionId;
+        const pendingTxId = pendingTransactionId;
         let pendingTransaction;
         try {
           pendingTransaction = yield (0, import_tracer.wrapWithSpan)(
@@ -2622,7 +2681,11 @@ const _ParaCore = class _ParaCore {
           );
         } catch (e) {
           const error = new import_errors.TransactionReviewDenied();
-          (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_TRANSACTION_EVENT, signRes, error.message);
+          (0, import_utils2.dispatchEvent)(
+            import_types.ParaEvent.SIGN_TRANSACTION_EVENT,
+            yield this.getDeniedSignatureResultWithUrl(pendingTxId),
+            error.message
+          );
           throw error;
         }
         if (!(pendingTransaction == null ? void 0 : pendingTransaction.approvedAt)) {
@@ -2646,16 +2709,16 @@ const _ParaCore = class _ParaCore {
           break;
         }
       }
-      if (signRes.pendingTransactionId) {
-        const error = new import_errors.TransactionReviewTimeout(
-          yield this.getTransactionReviewUrl(signRes.pendingTransactionId),
-          signRes.pendingTransactionId
-        );
-        (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_TRANSACTION_EVENT, signRes, error.message);
+      pendingTransactionId = getPendingTransactionId(signRes);
+      if (pendingTransactionId) {
+        const deniedSignRes = yield this.getDeniedSignatureResultWithUrl(pendingTransactionId);
+        const error = new import_errors.TransactionReviewTimeout(deniedSignRes.transactionReviewUrl, pendingTransactionId);
+        (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_TRANSACTION_EVENT, deniedSignRes, error.message);
         throw error;
       }
-      (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_TRANSACTION_EVENT, signRes);
-      return signRes;
+      const successfulSignRes = requireSuccessfulSignatureResult(signRes);
+      (0, import_utils2.dispatchEvent)(import_types.ParaEvent.SIGN_TRANSACTION_EVENT, successfulSignRes);
+      return successfulSignRes;
     });
   }
   isProviderModalDisabled() {

package/dist/cjs/constants.js

@@ -46,7 +46,7 @@ __export(constants_exports, {
   TRANSACTION_REVIEW_TIMEOUT_MS: () => TRANSACTION_REVIEW_TIMEOUT_MS
 });
 module.exports = __toCommonJS(constants_exports);
-const PARA_CORE_VERSION = "3.4.0";
+const PARA_CORE_VERSION = "3.5.1";
 const PREFIX = "@CAPSULE/";
 const PARA_PREFIX = "@PARA/";
 const LOCAL_STORAGE_AUTH_INFO = `${PREFIX}authInfo`;

package/dist/cjs/errors.js

@@ -18,6 +18,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var errors_exports = {};
 __export(errors_exports, {
   PartnerConfigError: () => PartnerConfigError,
+  SigningResultError: () => SigningResultError,
   TransactionReviewDenied: () => TransactionReviewDenied,
   TransactionReviewError: () => TransactionReviewError,
   TransactionReviewTimeout: () => TransactionReviewTimeout
@@ -44,6 +45,16 @@ class TransactionReviewTimeout extends Error {
     this.pendingTransactionId = pendingTransactionId;
   }
 }
+class SigningResultError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "SigningResultError";
+    this.code = options.code;
+    this.status = options.status;
+    this.responseURL = options.responseURL;
+    this.data = options.data;
+  }
+}
 class PartnerConfigError extends Error {
   constructor(code, message, detail) {
     super(message);
@@ -55,6 +66,7 @@ class PartnerConfigError extends Error {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PartnerConfigError,
+  SigningResultError,
   TransactionReviewDenied,
   TransactionReviewError,
   TransactionReviewTimeout

package/dist/cjs/services/AuthService.js

@@ -238,6 +238,11 @@ class AuthService {
             JSON.stringify(isSLOPossible)
           );
           return serverAuthState;
+        // No preparation needed
+        case "mfa":
+          return serverAuthState;
+        default:
+          return serverAuthState;
       }
     });
     this.prepareLoginState = (_0, _1) => __async(this, [_0, _1], function* (loginState, { useShortUrls: shorten = false, portalTheme, sessionLookupId }) {
@@ -489,10 +494,46 @@ class AuthService {
       return yield (0, import_stateListener.waitForAuthStateChange)({
         stateManager: __privateGet(this, _stateManager),
         resolvePhases: [
-          { phase: "awaiting_session_start", onPhase: (state) => state.authStateResult }
+          { phase: "awaiting_session_start", onPhase: (state) => state.authStateResult },
+          // Login-time 2FA (ENG-6906): the OAuth poll surfaced an mfa challenge instead
+          // of completing. Resolve here so the caller stops blocking; the challenge is
+          // read from the consumer auth state (AuthStateInfo.mfa) and satisfied via the
+          // enroll/verify hooks, which fire RESOLVE_2FA to continue the flow.
+          { phase: "awaiting_2fa", onPhase: (state) => state.authStateResult },
+          { phase: "awaiting_2fa_enrollment", onPhase: (state) => state.authStateResult }
         ]
       });
     });
+    /**
+     * 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.
+     */
+    this.resolveMfa = (pollingCallbacks) => __async(this, null, function* () {
+      __privateGet(this, _stateManager).send({ type: "RESOLVE_2FA", data: pollingCallbacks });
+      return yield (0, import_stateListener.waitForAuthStateChange)({
+        stateManager: __privateGet(this, _stateManager),
+        resolvePhases: [
+          { phase: "awaiting_session_start", onPhase: (state) => state.authStateResult },
+          { phase: "authenticated", onPhase: (state) => state.authStateResult }
+        ],
+        // If re-polling after the second factor lands in the auth error phase, reject fast
+        // with a clear message instead of stalling until the listener's default timeout. The
+        // caller stays parked at awaiting_2fa and can re-prompt/retry. (ENG-6906)
+        rejectPhases: [{ phase: "error", onPhase: () => new Error("Login 2FA resolution failed") }]
+      });
+    });
+    this.enrollMfa = () => __async(this, null, function* () {
+      return yield __privateGet(this, _paraCoreInterface).ctx.client.enrollMfa();
+    });
+    this.verifyMfa = (_0) => __async(this, [_0], function* ({ code }) {
+      const result = yield __privateGet(this, _paraCoreInterface).ctx.client.verifyMfa(code);
+      if (result.ok) {
+        yield this.resolveMfa();
+      }
+      return result;
+    });
     this.authenticateWithOAuth = (params) => __async(this, null, function* () {
       var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k;
       switch (params.method) {

package/dist/cjs/state/CoreStateManager.js

@@ -115,7 +115,7 @@ const _CoreStateManager = class _CoreStateManager {
    * Extracts all data needed by UI consumers from authStateResult.
    */
   computeAuthStateInfo(authContext, walletContext) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, _K, _L;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, _K, _L, _M, _N, _O, _P, _Q;
     const defaultAuthStateInfo = {
       userId: null,
       isPasskeySupported: false,
@@ -137,6 +137,7 @@ const _CoreStateManager = class _CoreStateManager {
       fallbackUsed: false,
       fallbackChannel: null,
       externalWalletVerification: null,
+      mfa: null,
       recoverySecret: null,
       isNewUser: false
     };
@@ -178,6 +179,7 @@ const _CoreStateManager = class _CoreStateManager {
     let deliveryChannel = null;
     let fallbackUsed = false;
     let fallbackChannel = null;
+    let mfa = null;
     if (stage === "login") {
       const loginState = authStateResult;
       const authMethods = (_j = loginState.loginAuthMethods) != null ? _j : [];
@@ -214,6 +216,17 @@ const _CoreStateManager = class _CoreStateManager {
       deliveryChannel = (_E = verifyState.deliveryChannel) != null ? _E : null;
       fallbackUsed = (_F = verifyState.fallbackUsed) != null ? _F : false;
       fallbackChannel = (_G = verifyState.fallbackChannel) != null ? _G : null;
+    } else if (stage === "mfa") {
+      const { mfa: challenge } = authStateResult;
+      mfa = {
+        mode: challenge.mode,
+        step: challenge.step,
+        methods: (_H = challenge.methods) != null ? _H : null,
+        attemptsRemaining: (_I = challenge.attemptsRemaining) != null ? _I : null,
+        lockedUntil: (_J = challenge.lockedUntil) != null ? _J : null,
+        secretUri: (_K = challenge.secretUri) != null ? _K : null,
+        backupCodes: (_L = challenge.backupCodes) != null ? _L : null
+      };
     }
     return {
       userId,
@@ -236,10 +249,11 @@ const _CoreStateManager = class _CoreStateManager {
       fallbackUsed,
       fallbackChannel,
       externalWalletVerification: externalWalletVerification ? {
-        signatureVerificationMessage: (_H = externalWalletVerification.signatureVerificationMessage) != null ? _H : "",
-        walletAddress: (_J = (_I = externalWalletVerification.externalWallet) == null ? void 0 : _I.address) != null ? _J : "",
-        walletType: (_L = (_K = externalWalletVerification.externalWallet) == null ? void 0 : _K.type) != null ? _L : ""
+        signatureVerificationMessage: (_M = externalWalletVerification.signatureVerificationMessage) != null ? _M : "",
+        walletAddress: (_O = (_N = externalWalletVerification.externalWallet) == null ? void 0 : _N.address) != null ? _O : "",
+        walletType: (_Q = (_P = externalWalletVerification.externalWallet) == null ? void 0 : _P.type) != null ? _Q : ""
       } : null,
+      mfa,
       recoverySecret,
       isNewUser
     };
@@ -300,10 +314,19 @@ const _CoreStateManager = class _CoreStateManager {
   }
   authStateInfoEqual(a, b) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _i;
-    return a.userId === b.userId && a.isPasskeySupported === b.isPasskeySupported && a.hasPasskey === b.hasPasskey && a.hasPassword === b.hasPassword && a.hasPin === b.hasPin && a.passkeyUrl === b.passkeyUrl && a.passkeyFullUrl === b.passkeyFullUrl && a.passkeyKnownDeviceUrl === b.passkeyKnownDeviceUrl && a.passwordUrl === b.passwordUrl && a.passwordFullUrl === b.passwordFullUrl && a.pinUrl === b.pinUrl && a.pinFullUrl === b.pinFullUrl && a.passkeyId === b.passkeyId && a.verificationUrl === b.verificationUrl && a.verificationFullUrl === b.verificationFullUrl && a.deliveryChannel === b.deliveryChannel && a.fallbackUsed === b.fallbackUsed && a.fallbackChannel === b.fallbackChannel && a.recoverySecret === b.recoverySecret && a.isNewUser === b.isNewUser && ((_a = a.externalWalletVerification) == null ? void 0 : _a.signatureVerificationMessage) === ((_b = b.externalWalletVerification) == null ? void 0 : _b.signatureVerificationMessage) && ((_c = a.externalWalletVerification) == null ? void 0 : _c.walletAddress) === ((_d = b.externalWalletVerification) == null ? void 0 : _d.walletAddress) && ((_e = a.externalWalletVerification) == null ? void 0 : _e.walletType) === ((_f = b.externalWalletVerification) == null ? void 0 : _f.walletType) && ((_g = a.passkeyHints) == null ? void 0 : _g.length) === ((_h = b.passkeyHints) == null ? void 0 : _h.length) && ((_i = a.passkeyHints) != null ? _i : []).every(
+    return a.userId === b.userId && a.isPasskeySupported === b.isPasskeySupported && a.hasPasskey === b.hasPasskey && a.hasPassword === b.hasPassword && a.hasPin === b.hasPin && a.passkeyUrl === b.passkeyUrl && a.passkeyFullUrl === b.passkeyFullUrl && a.passkeyKnownDeviceUrl === b.passkeyKnownDeviceUrl && a.passwordUrl === b.passwordUrl && a.passwordFullUrl === b.passwordFullUrl && a.pinUrl === b.pinUrl && a.pinFullUrl === b.pinFullUrl && a.passkeyId === b.passkeyId && a.verificationUrl === b.verificationUrl && a.verificationFullUrl === b.verificationFullUrl && a.deliveryChannel === b.deliveryChannel && a.fallbackUsed === b.fallbackUsed && a.fallbackChannel === b.fallbackChannel && a.recoverySecret === b.recoverySecret && a.isNewUser === b.isNewUser && ((_a = a.externalWalletVerification) == null ? void 0 : _a.signatureVerificationMessage) === ((_b = b.externalWalletVerification) == null ? void 0 : _b.signatureVerificationMessage) && ((_c = a.externalWalletVerification) == null ? void 0 : _c.walletAddress) === ((_d = b.externalWalletVerification) == null ? void 0 : _d.walletAddress) && ((_e = a.externalWalletVerification) == null ? void 0 : _e.walletType) === ((_f = b.externalWalletVerification) == null ? void 0 : _f.walletType) && this.mfaEqual(a.mfa, b.mfa) && ((_g = a.passkeyHints) == null ? void 0 : _g.length) === ((_h = b.passkeyHints) == null ? void 0 : _h.length) && ((_i = a.passkeyHints) != null ? _i : []).every(
       (hint, i) => hint.useragent === b.passkeyHints[i].useragent && hint.aaguid === b.passkeyHints[i].aaguid
     );
   }
+  mfaEqual(a, b) {
+    if (a === b) return true;
+    if (!a || !b) return false;
+    const sameStringArray = (x, y) => {
+      var _a, _b;
+      return ((_a = x == null ? void 0 : x.length) != null ? _a : -1) === ((_b = y == null ? void 0 : y.length) != null ? _b : -1) && (x != null ? x : []).every((v, i) => v === y[i]);
+    };
+    return a.mode === b.mode && a.step === b.step && a.attemptsRemaining === b.attemptsRemaining && a.lockedUntil === b.lockedUntil && a.secretUri === b.secretUri && sameStringArray(a.methods, b.methods) && sameStringArray(a.backupCodes, b.backupCodes);
+  }
 };
 _CoreStateManager.CORE_LOADING_STATES = /* @__PURE__ */ new Set([
   "setting_up",
@@ -317,7 +340,11 @@ _CoreStateManager.AUTH_LOADING_STATES = /* @__PURE__ */ new Set([
   "authenticating_farcaster",
   "processing_authentication",
   "authenticating_telegram",
-  "checking_state"
+  "checking_state",
+  // Re-polling the login status after the second factor is satisfied (ENG-6906).
+  // awaiting_2fa / awaiting_2fa_enrollment are deliberately NOT loading — they are
+  // user-input holds where the UI shows the MFA prompt.
+  "resolving_2fa"
 ]);
 _CoreStateManager.WALLET_LOADING_STATES = /* @__PURE__ */ new Set([
   "checking_wallet_state",

package/dist/cjs/state/machines/authStateMachine.js

@@ -756,18 +756,18 @@ function createAuthStateMachine(paraCoreInterface) {
               guard: (0, import_xstate.and)([
                 ({ event }) => {
                   const output = event.output;
-                  return !!output.externalWallet;
+                  return !!(output == null ? void 0 : output.externalWallet);
                 },
                 (0, import_xstate.or)([
                   ({ event }) => {
                     var _a;
                     const output = event.output;
-                    return output.stage === "done" && !((_a = output.externalWallet) == null ? void 0 : _a.withFullParaAuth);
+                    return (output == null ? void 0 : output.stage) === "done" && !((_a = output == null ? void 0 : output.externalWallet) == null ? void 0 : _a.withFullParaAuth);
                   },
                   ({ event }) => {
                     var _a, _b;
                     const output = event.output;
-                    return output.stage === "verify" && !((_a = output.externalWallet) == null ? void 0 : _a.withFullParaAuth) && !((_b = output.externalWallet) == null ? void 0 : _b.withVerification);
+                    return (output == null ? void 0 : output.stage) === "verify" && !((_a = output == null ? void 0 : output.externalWallet) == null ? void 0 : _a.withFullParaAuth) && !((_b = output == null ? void 0 : output.externalWallet) == null ? void 0 : _b.withVerification);
                   }
                 ])
               ])
@@ -784,12 +784,12 @@ function createAuthStateMachine(paraCoreInterface) {
               guard: (0, import_xstate.and)([
                 ({ event }) => {
                   const output = event.output;
-                  return !!output.externalWallet;
+                  return !!(output == null ? void 0 : output.externalWallet);
                 },
                 ({ event }) => {
                   var _a, _b;
                   const output = event.output;
-                  return output.stage === "verify" && !((_a = output.externalWallet) == null ? void 0 : _a.withFullParaAuth) && ((_b = output.externalWallet) == null ? void 0 : _b.withVerification);
+                  return (output == null ? void 0 : output.stage) === "verify" && !((_a = output == null ? void 0 : output.externalWallet) == null ? void 0 : _a.withFullParaAuth) && ((_b = output == null ? void 0 : output.externalWallet) == null ? void 0 : _b.withVerification);
                 }
               ])
             },
@@ -805,12 +805,12 @@ function createAuthStateMachine(paraCoreInterface) {
               guard: (0, import_xstate.and)([
                 ({ event }) => {
                   const output = event.output;
-                  return !!output.externalWallet;
+                  return !!(output == null ? void 0 : output.externalWallet);
                 },
                 ({ event }) => {
                   var _a;
                   const output = event.output;
-                  return output.stage === "verify" && !!((_a = output.externalWallet) == null ? void 0 : _a.withFullParaAuth);
+                  return (output == null ? void 0 : output.stage) === "verify" && !!((_a = output == null ? void 0 : output.externalWallet) == null ? void 0 : _a.withFullParaAuth);
                 }
               ])
             },
@@ -824,11 +824,37 @@ function createAuthStateMachine(paraCoreInterface) {
                 ({ event }) => {
                   var _a;
                   const output = event.output;
-                  return output.stage === "verify" && !((_a = output.externalWallet) == null ? void 0 : _a.withFullParaAuth);
+                  return (output == null ? void 0 : output.stage) === "verify" && !((_a = output == null ? void 0 : output.externalWallet) == null ? void 0 : _a.withFullParaAuth);
                 },
                 () => !paraCoreInterface.authService.isEnclaveUser
               ])
             },
+            // Login-time 2FA (ENG-6906): the server gated the login behind a second
+            // factor. Enrollment (no factor yet) and verification (existing factor)
+            // are surfaced as distinct phases so a custom UI can show the right step.
+            {
+              target: "awaiting_2fa_enrollment",
+              actions: [
+                "storeAuthStateResult",
+                { type: "logTransition", params: { to: "awaiting_2fa_enrollment", detail: "mfa enroll" } }
+              ],
+              guard: ({ event }) => {
+                var _a;
+                const output = event.output;
+                return (output == null ? void 0 : output.stage) === "mfa" && ((_a = output == null ? void 0 : output.mfa) == null ? void 0 : _a.mode) === "enroll";
+              }
+            },
+            {
+              target: "awaiting_2fa",
+              actions: [
+                "storeAuthStateResult",
+                { type: "logTransition", params: { to: "awaiting_2fa", detail: "mfa verify" } }
+              ],
+              guard: ({ event }) => {
+                const output = event.output;
+                return (output == null ? void 0 : output.stage) === "mfa";
+              }
+            },
             {
               target: "awaiting_session_start",
               actions: [
@@ -871,6 +897,77 @@ function createAuthStateMachine(paraCoreInterface) {
           CANCEL: { target: "unauthenticated", actions: ["resetState"] }
         }
       },
+      // Login-time 2FA hold states (ENG-6906). The SDK satisfies the second factor
+      // out-of-band (enrollMfa/verifyMfa against /internal/v1/auth/2fa/*); once the
+      // backend has stamped the session, a RESOLVE_2FA event re-polls the login
+      // status, which now returns stage:'done'.
+      awaiting_2fa: {
+        on: {
+          RESOLVE_2FA: { target: "resolving_2fa", actions: ["setPollingCallbacks", "resetError"] },
+          CANCEL: { target: "unauthenticated", actions: ["resetState"] }
+        }
+      },
+      awaiting_2fa_enrollment: {
+        on: {
+          RESOLVE_2FA: { target: "resolving_2fa", actions: ["setPollingCallbacks", "resetError"] },
+          CANCEL: { target: "unauthenticated", actions: ["resetState"] }
+        }
+      },
+      resolving_2fa: {
+        entry: [{ type: "logTransition", params: { to: "resolving_2fa" } }],
+        invoke: {
+          src: "polling",
+          input: ({ context }) => {
+            var _a;
+            let resolvedAuthState = null;
+            return {
+              checkCondition: () => __async(this, null, function* () {
+                try {
+                  const result = yield paraCoreInterface.pollingService.waitForOAuth({
+                    onSuccess: (serverAuthState) => {
+                      resolvedAuthState = serverAuthState;
+                    }
+                  })();
+                  return { finished: result.finished && !!resolvedAuthState, data: { authState: resolvedAuthState } };
+                } catch (error) {
+                  throw new Error(`2FA resolution polling failed: ${(0, import_stateErrorHelpers.extractErrorMessage)(error, "Unknown error")}`);
+                }
+              }),
+              onPoll: () => {
+                var _a2, _b;
+                return (_b = (_a2 = context.pollingCallbacks) == null ? void 0 : _a2.onPoll) == null ? void 0 : _b.call(_a2);
+              },
+              onCancel: () => {
+                var _a2, _b;
+                return (_b = (_a2 = context.pollingCallbacks) == null ? void 0 : _a2.onCancel) == null ? void 0 : _b.call(_a2);
+              },
+              isCanceled: ((_a = context.pollingCallbacks) == null ? void 0 : _a.isCanceled) || (() => false),
+              id: "resolving2fa"
+            };
+          },
+          onError: {
+            target: "error",
+            actions: (0, import_authStateMachine_helpers.setAuthErrorAssign)("2FA resolution failed")
+          }
+        },
+        on: (0, import_authStateMachine_helpers.makePollingOnHandlers)("processing_authentication", "2FA resolution failed", [
+          (0, import_xstate.assign)({
+            serverAuthStateResult: ({ event }) => {
+              var _a;
+              const authState = ((_a = event.data) == null ? void 0 : _a.authState) || null;
+              return {
+                authState,
+                opts: import_authStateMachine_helpers.DEFAULT_AUTH_OPTS
+              };
+            },
+            isNewUser: ({ event }) => {
+              var _a;
+              const authState = (_a = event.data) == null ? void 0 : _a.authState;
+              return authState ? (0, import_authStateMachine_helpers.computeIsNewUser)(authState) : false;
+            }
+          })
+        ])
+      },
       awaiting_session_start: {
         on: {
           WAIT_FOR_SESSION: {

package/dist/cjs/state/machines/coreStateMachine.js

@@ -219,6 +219,14 @@ function createCoreStateMachine(paraCoreInterface) {
           "WAIT_FOR_WALLET_CREATION": {
             actions: ({ context, event }) => context.authMachineRef.send(event)
           },
+          // Login-time 2FA (ENG-6906): after the second factor is satisfied, verifyMfa
+          // fires RESOLVE_2FA so the auth machine re-polls verify-oauth and advances the
+          // login. Without forwarding it here the parent silently drops the event, the
+          // auth child stays parked at awaiting_2fa[_enrollment], and the user never gets
+          // a wallet.
+          "RESOLVE_2FA": {
+            actions: ({ context, event }) => context.authMachineRef.send(event)
+          },
           "INITIALIZE_GUEST_MODE": {
             actions: ({ context, event }) => context.authMachineRef.send(event)
           },

package/dist/cjs/types/coreApi.js

@@ -39,6 +39,8 @@ const PARA_CORE_METHODS = [
   "setup2fa",
   "enable2fa",
   "verify2fa",
+  "enrollMfa",
+  "verifyMfa",
   "logout",
   "clearStorage",
   "isSessionActive",