@getpara/core-sdk 3.4.0 → 3.5.1

package/dist/esm/ParaCore.js

@@ -54,7 +54,7 @@ import {
 import { waitForAuthStateChange } from "./utils/stateListener.js";
 import { warnOnce } from "./utils/deprecation.js";
 import { assertConfigAllowed } from "./utils/partnerConfigGating.js";
-import { TransactionReviewDenied, TransactionReviewTimeout } from "./errors.js";
+import { SigningResultError, TransactionReviewDenied, TransactionReviewTimeout } from "./errors.js";
 import * as constants from "./constants.js";
 import { EnclaveClient } from "./shares/enclave.js";
 import { AuthService } from "./services/AuthService.js";
@@ -69,6 +69,24 @@ import { wrapWithSpan } from "./telemetry/tracer.js";
 import { setCurrentUserId } from "./telemetry/uxStateSpanProcessor.js";
 import { initTelemetry } from "./telemetry/init.js";
 import { recordActionOnSpan } from "./telemetry/uxAction.js";
+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 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);
@@ -1770,6 +1788,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.
    */
@@ -2331,6 +2380,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
@@ -2393,11 +2450,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 {
@@ -2406,8 +2461,9 @@ const _ParaCore = class _ParaCore {
           });
         }
       } else {
-        dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, signRes);
-        return signRes;
+        const successfulSignRes2 = requireSuccessfulSignatureResult(signRes);
+        dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, successfulSignRes2);
+        return successfulSignRes2;
       }
       while (true) {
         if (isCanceled() || Date.now() - timeStart > effectiveTimeoutMs) {
@@ -2421,15 +2477,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 TransactionReviewDenied();
-          dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, signRes, error.message);
+          dispatchEvent(
+            ParaEvent.SIGN_MESSAGE_EVENT,
+            yield this.getDeniedSignatureResultWithUrl(pendingTransactionId),
+            error.message
+          );
           throw error;
         }
         if (!(pendingTransaction == null ? void 0 : pendingTransaction.approvedAt)) {
@@ -2444,16 +2504,16 @@ const _ParaCore = class _ParaCore {
           break;
         }
       }
-      if (signRes.pendingTransactionId) {
-        const error = new TransactionReviewTimeout(
-          yield this.getTransactionReviewUrl(signRes.pendingTransactionId),
-          signRes.pendingTransactionId
-        );
-        dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, signRes, error.message);
+      pendingTransactionId = getPendingTransactionId(signRes);
+      if (pendingTransactionId) {
+        const deniedSignRes = yield this.getDeniedSignatureResultWithUrl(pendingTransactionId);
+        const error = new TransactionReviewTimeout(deniedSignRes.transactionReviewUrl, pendingTransactionId);
+        dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, deniedSignRes, error.message);
         throw error;
       }
-      dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, signRes);
-      return signRes;
+      const successfulSignRes = requireSuccessfulSignatureResult(signRes);
+      dispatchEvent(ParaEvent.SIGN_MESSAGE_EVENT, successfulSignRes);
+      return successfulSignRes;
     });
   }
   signMessageInner(_0) {
@@ -2532,19 +2592,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: PopupType.SIGN_TRANSACTION_REVIEW });
         }
       } else {
-        dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, signRes);
-        return signRes;
+        const successfulSignRes2 = requireSuccessfulSignatureResult(signRes);
+        dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, successfulSignRes2);
+        return successfulSignRes2;
       }
       while (true) {
         if (isCanceled() || Date.now() - timeStart > effectiveTimeoutMs) {
@@ -2552,7 +2611,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 wrapWithSpan(
@@ -2567,7 +2626,11 @@ const _ParaCore = class _ParaCore {
           );
         } catch (e) {
           const error = new TransactionReviewDenied();
-          dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, signRes, error.message);
+          dispatchEvent(
+            ParaEvent.SIGN_TRANSACTION_EVENT,
+            yield this.getDeniedSignatureResultWithUrl(pendingTxId),
+            error.message
+          );
           throw error;
         }
         if (!(pendingTransaction == null ? void 0 : pendingTransaction.approvedAt)) {
@@ -2591,16 +2654,16 @@ const _ParaCore = class _ParaCore {
           break;
         }
       }
-      if (signRes.pendingTransactionId) {
-        const error = new TransactionReviewTimeout(
-          yield this.getTransactionReviewUrl(signRes.pendingTransactionId),
-          signRes.pendingTransactionId
-        );
-        dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, signRes, error.message);
+      pendingTransactionId = getPendingTransactionId(signRes);
+      if (pendingTransactionId) {
+        const deniedSignRes = yield this.getDeniedSignatureResultWithUrl(pendingTransactionId);
+        const error = new TransactionReviewTimeout(deniedSignRes.transactionReviewUrl, pendingTransactionId);
+        dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, deniedSignRes, error.message);
         throw error;
       }
-      dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, signRes);
-      return signRes;
+      const successfulSignRes = requireSuccessfulSignatureResult(signRes);
+      dispatchEvent(ParaEvent.SIGN_TRANSACTION_EVENT, successfulSignRes);
+      return successfulSignRes;
     });
   }
   isProviderModalDisabled() {

package/dist/esm/constants.js

@@ -1,5 +1,5 @@
 import "./chunk-7B52C2XE.js";
-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/esm/errors.js

@@ -20,6 +20,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);
@@ -30,6 +40,7 @@ class PartnerConfigError extends Error {
 }
 export {
   PartnerConfigError,
+  SigningResultError,
   TransactionReviewDenied,
   TransactionReviewError,
   TransactionReviewTimeout

package/dist/esm/services/AuthService.js

@@ -169,6 +169,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 }) {
@@ -420,10 +425,46 @@ class AuthService {
       return yield 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 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/esm/state/CoreStateManager.js

@@ -80,7 +80,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,
@@ -102,6 +102,7 @@ const _CoreStateManager = class _CoreStateManager {
       fallbackUsed: false,
       fallbackChannel: null,
       externalWalletVerification: null,
+      mfa: null,
       recoverySecret: null,
       isNewUser: false
     };
@@ -143,6 +144,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 : [];
@@ -179,6 +181,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,
@@ -201,10 +214,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
     };
@@ -265,10 +279,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",
@@ -282,7 +305,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/esm/state/machines/authStateMachine.js

@@ -712,18 +712,18 @@ function createAuthStateMachine(paraCoreInterface) {
               guard: and([
                 ({ event }) => {
                   const output = event.output;
-                  return !!output.externalWallet;
+                  return !!(output == null ? void 0 : output.externalWallet);
                 },
                 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);
                   }
                 ])
               ])
@@ -740,12 +740,12 @@ function createAuthStateMachine(paraCoreInterface) {
               guard: 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);
                 }
               ])
             },
@@ -761,12 +761,12 @@ function createAuthStateMachine(paraCoreInterface) {
               guard: 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);
                 }
               ])
             },
@@ -780,11 +780,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: [
@@ -827,6 +853,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: ${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: setAuthErrorAssign("2FA resolution failed")
+          }
+        },
+        on: makePollingOnHandlers("processing_authentication", "2FA resolution failed", [
+          assign({
+            serverAuthStateResult: ({ event }) => {
+              var _a;
+              const authState = ((_a = event.data) == null ? void 0 : _a.authState) || null;
+              return {
+                authState,
+                opts: DEFAULT_AUTH_OPTS
+              };
+            },
+            isNewUser: ({ event }) => {
+              var _a;
+              const authState = (_a = event.data) == null ? void 0 : _a.authState;
+              return authState ? computeIsNewUser(authState) : false;
+            }
+          })
+        ])
+      },
       awaiting_session_start: {
         on: {
           WAIT_FOR_SESSION: {

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

@@ -180,6 +180,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/esm/types/coreApi.js

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