@dynamic-labs/legacy-embedded-wallet-migration 0.0.0 → 5.0.0-rc.2

package/src/lib/sessionKeys/useRegisterEmbeddedWalletSessionKey/useRegisterEmbeddedWalletSessionKey.js

@@ -0,0 +1,101 @@
+'use client'
+import { __awaiter } from '../../../../_virtual/_tslib.js';
+import { useCallback } from 'react';
+import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
+import { tracing, StorageService, InvalidEmbeddedWalletSessionKeyError } from '@dynamic-labs/utils';
+import { logger } from '@dynamic-labs/wallet-connector-core';
+import { SECURE_ENCLAVE_WALLET_SESSION_KEYS, SECURE_ENCLAVE_WALLET_SESSION_KEYS_STORAGE_OPTIONS } from '../../constants.js';
+import { getTurnkeyWalletId } from '../../getTurnkeyWalletId/getTurnkeyWalletId.js';
+import { generateAndSaveSessionKey } from '../generateAndSaveSessionKey/generateAndSaveSessionKey.js';
+import { generateSessionKey } from '../generateSessionKey/generateSessionKey.js';
+import { getDecodedSessionKeys } from '../getDecodedSessionKeys/getDecodedSessionKeys.js';
+import { p256Sign } from '../p256Sign/p256Sign.js';
+import { registerSessionKey } from '../registerSessionKey/registerSessionKey.js';
+import { toEncodedFormat } from '../toEncodedFormat/toEncodedFormat.js';
+
+const resolveSessionKeyForRegistration = (existing, sessionId) => __awaiter(void 0, void 0, void 0, function* () {
+    if (!existing.registered) {
+        return {
+            prevSessionKeySignature: undefined,
+            privateKey: existing.privateKey,
+            privateKeyJwk: existing.privateKeyJwk,
+            publicKey: existing.publicKey,
+        };
+    }
+    const prevSessionKeySignature = yield p256Sign(existing.privateKeyJwk, sessionId);
+    const fresh = yield generateSessionKey();
+    tracing.logEvent('session-key', 'Loaded prevSessionKeySignature', tracing.formatObject({
+        prevSessionKeySignature,
+        publicKey: fresh.publicKey,
+    }));
+    return {
+        prevSessionKeySignature,
+        privateKey: fresh.privateKey,
+        privateKeyJwk: fresh.privateKeyJwk,
+        publicKey: fresh.publicKey,
+    };
+});
+const safeRegisterSessionKey = (_a) => __awaiter(void 0, [_a], void 0, function* ({ handleLogOut, prevSessionKeySignature, publicKey, walletId, }) {
+    try {
+        return yield registerSessionKey({
+            prevSessionKeySignature,
+            publicKey,
+            walletId,
+        });
+    }
+    catch (error) {
+        if (error instanceof InvalidEmbeddedWalletSessionKeyError) {
+            logger.warn('Invalid embedded wallet session key. Re-authentication is required to create new session keys.');
+            yield handleLogOut();
+        }
+        logger.error('Error registering session key', { error });
+        throw error;
+    }
+});
+const useRegisterEmbeddedWalletSessionKey = () => {
+    const { user, handleLogOut } = useDynamicContext();
+    return useCallback((_a) => __awaiter(void 0, [_a], void 0, function* ({ ignoreRestore = false, walletId, }) {
+        if (!user) {
+            throw new Error('User not found');
+        }
+        let existingSessionKey = getDecodedSessionKeys();
+        tracing.logEvent('session-key', 'registerEmbeddedWalletSessionKey', tracing.formatObject({
+            hasDecodedSessionKeys: Boolean(existingSessionKey),
+            publicKey: existingSessionKey === null || existingSessionKey === void 0 ? void 0 : existingSessionKey.publicKey,
+        }));
+        if (!existingSessionKey) {
+            logger.error('Session keys not found in storage. Generating new session keys.', { userId: user.userId });
+            existingSessionKey = yield generateAndSaveSessionKey();
+        }
+        const isSessionKeyValid = existingSessionKey.registered &&
+            existingSessionKey.expirationDate &&
+            new Date() <= new Date(existingSessionKey.expirationDate) &&
+            !ignoreRestore;
+        tracing.logEvent('session-key', 'isSessionKeyValid', tracing.formatObject({ isSessionKeyValid: Boolean(isSessionKeyValid) }));
+        if (isSessionKeyValid) {
+            return existingSessionKey;
+        }
+        tracing.logEvent('session-key', 'decodedSessionKeys', tracing.formatObject({
+            publicKey: existingSessionKey.publicKey,
+            registered: existingSessionKey.registered,
+        }));
+        const { publicKey, privateKey, privateKeyJwk, prevSessionKeySignature } = yield resolveSessionKeyForRegistration(existingSessionKey, user.sessionId);
+        const turnkeyWalletId = getTurnkeyWalletId(walletId, user.verifiedCredentials);
+        const resp = yield safeRegisterSessionKey({
+            handleLogOut,
+            prevSessionKeySignature,
+            publicKey,
+            walletId: turnkeyWalletId,
+        });
+        const expirationDate = new Date(resp.expiresAt * 1000);
+        tracing.logEvent('session-key', 'Created new session key', tracing.formatObject({ expirationDate, publicKey }));
+        StorageService.setItem(SECURE_ENCLAVE_WALLET_SESSION_KEYS, toEncodedFormat(publicKey, privateKey, privateKeyJwk, true, expirationDate), SECURE_ENCLAVE_WALLET_SESSION_KEYS_STORAGE_OPTIONS);
+        return {
+            expirationDate,
+            privateKey,
+            publicKey,
+        };
+    }), [handleLogOut, user]);
+};
+
+export { useRegisterEmbeddedWalletSessionKey };

package/src/lib/sessionKeys/useSetTurnkeyConnectorFetchers/index.d.ts

@@ -0,0 +1 @@
+export { useSetTurnkeyConnectorFetchers } from './useSetTurnkeyConnectorFetchers';

package/src/lib/sessionKeys/useSetTurnkeyConnectorFetchers/useSetTurnkeyConnectorFetchers.d.ts

@@ -0,0 +1,4 @@
+import { Wallet, WalletConnectorCore } from '@dynamic-labs/wallet-connector-core';
+export declare const useSetTurnkeyConnectorFetchers: ({ wallet, }: {
+    wallet: Wallet<WalletConnectorCore.WalletConnector> | null;
+}) => (() => void);

package/src/lib/sessionKeys/useSetTurnkeyConnectorFetchers/useSetTurnkeyConnectorFetchers.js

@@ -0,0 +1,18 @@
+'use client'
+import { useCallback } from 'react';
+import { isSessionKeyCompatibleWalletConnector } from '@dynamic-labs/wallet-connector-core';
+import { removeSessionKey } from '../removeSessionKey/removeSessionKey.js';
+import { useRegisterEmbeddedWalletSessionKey } from '../useRegisterEmbeddedWalletSessionKey/useRegisterEmbeddedWalletSessionKey.js';
+
+const useSetTurnkeyConnectorFetchers = ({ wallet, }) => {
+    const registerEmbeddedWalletSessionKey = useRegisterEmbeddedWalletSessionKey();
+    return useCallback(() => {
+        const connector = wallet === null || wallet === void 0 ? void 0 : wallet.connector;
+        if (!isSessionKeyCompatibleWalletConnector(connector))
+            return;
+        connector.setSessionKeyFetcher(registerEmbeddedWalletSessionKey);
+        connector.setSessionKeyRemoveFunction(() => removeSessionKey());
+    }, [wallet, registerEmbeddedWalletSessionKey]);
+};
+
+export { useSetTurnkeyConnectorFetchers };

package/src/lib/softDeleteEmbeddedWallet/index.d.ts

@@ -0,0 +1 @@
+export { softDeleteEmbeddedWallet } from './softDeleteEmbeddedWallet';

package/src/lib/softDeleteEmbeddedWallet/softDeleteEmbeddedWallet.d.ts

@@ -0,0 +1,5 @@
+type SoftDeleteEmbeddedWalletProps = {
+    walletId: string;
+};
+export declare const softDeleteEmbeddedWallet: ({ walletId, }: SoftDeleteEmbeddedWalletProps) => Promise<void>;
+export {};

package/src/lib/softDeleteEmbeddedWallet/softDeleteEmbeddedWallet.js

@@ -0,0 +1,21 @@
+'use client'
+import { __awaiter } from '../../../_virtual/_tslib.js';
+import { getDefaultClient, getCore, createApiClient } from '@dynamic-labs-sdk/client/core';
+import { DynamicError } from '@dynamic-labs/utils';
+
+const softDeleteEmbeddedWallet = (_a) => __awaiter(void 0, [_a], void 0, function* ({ walletId, }) {
+    const client = getDefaultClient();
+    const core = getCore(client);
+    const apiClient = createApiClient({}, client);
+    try {
+        yield apiClient.softDeleteEmbeddedWallet({
+            environmentId: core.environmentId,
+            walletId,
+        });
+    }
+    catch (e) {
+        throw new DynamicError('Error soft-deleting embedded wallet', 'soft_delete_embedded_wallet_failed');
+    }
+});
+
+export { softDeleteEmbeddedWallet };

package/src/lib/ui/AccountUpgradedView/AccountUpgradedView.d.ts

@@ -0,0 +1,5 @@
+import { FC } from 'react';
+export type AccountUpgradedViewProps = {
+    onFinish: () => void;
+};
+export declare const AccountUpgradedView: FC<AccountUpgradedViewProps>;

package/src/lib/ui/AccountUpgradedView/AccountUpgradedView.js

@@ -0,0 +1,44 @@
+'use client'
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { useTranslation } from 'react-i18next';
+import { IconButton, ModalHeader, Typography, TypographyButton } from '@dynamic-labs/sdk-react-core/components';
+import { CloseIcon, SparklesIcon } from '@dynamic-labs/sdk-react-core/icons';
+
+const containerStyle = {
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '40px',
+    padding: '32px 24px 24px 24px',
+};
+const contentStyle = {
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '32px',
+    justifyContent: 'center',
+};
+const iconBackgroundStyle = {
+    alignItems: 'center',
+    background: 'var(--dynamic-brand-primary-color)',
+    borderRadius: '50%',
+    boxShadow: '0 8px 24px rgb(0 0 0 / 12%)',
+    display: 'flex',
+    height: 88,
+    justifyContent: 'center',
+    width: 88,
+};
+const iconStyle = { color: 'white', height: 44, width: 44 };
+const messageStyle = {
+    lineHeight: 1.5,
+    maxWidth: 340,
+    textAlign: 'center',
+};
+const actionsStyle = { maxWidth: 340, width: '100%' };
+const AccountUpgradedView = ({ onFinish, }) => {
+    const { t } = useTranslation();
+    const closeButton = (jsx(IconButton, { onClick: onFinish, type: 'button', children: jsx(CloseIcon, {}) }));
+    return (jsxs(Fragment, { children: [jsx(ModalHeader, { trailing: closeButton, displayBorder: true, children: jsx(Typography, { variant: 'title', color: 'primary', children: t('dyn_account_upgraded.title') }) }), jsxs("div", { style: containerStyle, children: [jsxs("div", { style: contentStyle, children: [jsx("div", { style: iconBackgroundStyle, children: jsx(SparklesIcon, { style: iconStyle }) }), jsx("div", { style: messageStyle, children: jsx(Typography, { variant: 'body_normal', color: 'primary', style: { textAlign: 'center' }, children: t('dyn_account_upgraded.message') }) })] }), jsx("div", { style: actionsStyle, children: jsx(TypographyButton, { onClick: onFinish, buttonVariant: 'brand-primary', expanded: true, buttonPadding: 'large', typographyProps: { color: 'white' }, dataTestId: 'account-upgraded-continue-button', children: t('dyn_account_upgraded.continue_button') }) })] })] }));
+};
+
+export { AccountUpgradedView };

package/src/lib/ui/AccountUpgradedView/index.d.ts

@@ -0,0 +1 @@
+export { AccountUpgradedView, type AccountUpgradedViewProps, } from './AccountUpgradedView';

package/src/lib/ui/LegacyEmbeddedWalletExport/LegacyEmbeddedWalletExport.d.ts

@@ -0,0 +1,6 @@
+import { FC } from 'react';
+import { Wallet, WalletConnectorCore } from '@dynamic-labs/wallet-connector-core';
+export type LegacyEmbeddedWalletExportProps = {
+    wallet: Wallet<WalletConnectorCore.WalletConnector>;
+};
+export declare const LegacyEmbeddedWalletExport: FC<LegacyEmbeddedWalletExportProps>;

package/src/lib/ui/LegacyEmbeddedWalletExport/LegacyEmbeddedWalletExport.js

@@ -0,0 +1,122 @@
+'use client'
+import { __awaiter } from '../../../../_virtual/_tslib.js';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { useRef, useState, useEffect } from 'react';
+import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
+import { isSessionKeyCompatibleWalletConnector, isTurnkeyWalletConnector, logger } from '@dynamic-labs/wallet-connector-core';
+import { iframeContainerId, iframeElementId } from '../../constants.js';
+import { cleanupExport } from '../../export/cleanupExport/cleanupExport.js';
+import { exportTurnkeyWalletCredential } from '../../export/exportTurnkeyWalletCredential/exportTurnkeyWalletCredential.js';
+import { initExport } from '../../export/initExport/initExport.js';
+import { useSetTurnkeyConnectorFetchers } from '../../sessionKeys/useSetTurnkeyConnectorFetchers/useSetTurnkeyConnectorFetchers.js';
+
+const credentialContainerStyle = {
+    alignItems: 'center',
+    display: 'flex',
+    justifyContent: 'center',
+    minHeight: 64,
+    position: 'relative',
+    width: '100%',
+};
+const iframeContainerStyle = {
+    background: 'var(--dynamic-base-3, #f5f5f5)',
+    borderRadius: 8,
+    minHeight: 64,
+    padding: 12,
+    width: '100%',
+    wordBreak: 'break-all',
+};
+const hiddenIframeContainerStyle = Object.assign(Object.assign({}, iframeContainerStyle), { visibility: 'hidden' });
+const skeletonContainerStyle = {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 8,
+    inset: 12,
+    position: 'absolute',
+};
+const skeletonLineStyle = {
+    background: 'var(--dynamic-base-4, #e5e5e5)',
+    borderRadius: 4,
+    height: 12,
+    width: '100%',
+};
+const skeletonLineShortStyle = Object.assign(Object.assign({}, skeletonLineStyle), { width: '60%' });
+const LegacyEmbeddedWalletExport = ({ wallet }) => {
+    const { user } = useDynamicContext();
+    const setTurnkeyConnectorFetchers = useSetTurnkeyConnectorFetchers({
+        wallet,
+    });
+    const containerRef = useRef(null);
+    const isExportingRef = useRef(false);
+    const [revealed, setRevealed] = useState(false);
+    const setContainerRef = (element) => {
+        containerRef.current = element;
+    };
+    // Store in refs so the effect doesn't re-fire when their references change.
+    const setFetchersRef = useRef(setTurnkeyConnectorFetchers);
+    setFetchersRef.current = setTurnkeyConnectorFetchers;
+    const userRef = useRef(user);
+    userRef.current = user;
+    const walletRef = useRef(wallet);
+    walletRef.current = wallet;
+    // Export flow — runs once on mount. The isExportingRef guard prevents
+    // re-entry if React re-fires the effect due to reference changes.
+    useEffect(() => {
+        const run = () => __awaiter(void 0, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const iframeContainer = containerRef.current;
+            if (!iframeContainer || iframeContainer.children.length > 0) {
+                return;
+            }
+            if (isExportingRef.current) {
+                return;
+            }
+            isExportingRef.current = true;
+            try {
+                setFetchersRef.current();
+                if (isSessionKeyCompatibleWalletConnector(wallet === null || wallet === void 0 ? void 0 : wallet.connector)) {
+                    yield ((_a = wallet === null || wallet === void 0 ? void 0 : wallet.connector) === null || _a === void 0 ? void 0 : _a.createOrRestoreSession());
+                }
+                if (isTurnkeyWalletConnector(wallet === null || wallet === void 0 ? void 0 : wallet.connector)) {
+                    yield ((_b = wallet === null || wallet === void 0 ? void 0 : wallet.connector) === null || _b === void 0 ? void 0 : _b.getTurnkeyClient());
+                }
+                // Remove any leftover iframe from a previous wallet export. The
+                // export handler is a static singleton shared across all Turnkey
+                // connectors; when switching wallets, the previous component's
+                // cleanup may not have fully completed before this effect fires,
+                // so the IframeStamper constructor would throw "already exists".
+                (_c = iframeContainer.querySelector(`#${iframeElementId}`)) === null || _c === void 0 ? void 0 : _c.remove();
+                yield initExport({
+                    iframeContainer,
+                    iframeElementId,
+                    wallet,
+                });
+                yield exportTurnkeyWalletCredential({
+                    exportPrivateKey: true,
+                    user: userRef.current,
+                    wallet,
+                });
+                setRevealed(true);
+            }
+            catch (error) {
+                logger.error('LegacyEmbeddedWalletExport: export flow failed', error);
+            }
+            finally {
+                isExportingRef.current = false;
+            }
+        });
+        run();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [wallet]);
+    // Cleanup on unmount only — do not run on dep-change re-fires.
+    useEffect(() => () => {
+        cleanupExport({ wallet: walletRef.current }).catch(() => {
+            // Swallow — component is unmounting.
+        });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    return (jsxs("div", { style: credentialContainerStyle, children: [jsx("div", { id: iframeContainerId, ref: setContainerRef, style: revealed ? iframeContainerStyle : hiddenIframeContainerStyle }), !revealed && (jsxs("div", { style: skeletonContainerStyle, children: [jsx("div", { style: skeletonLineStyle, "data-testid": 'private-key-skeleton' }), jsx("div", { style: skeletonLineStyle }), jsx("div", { style: skeletonLineShortStyle })] }))] }));
+};
+
+export { LegacyEmbeddedWalletExport };

package/src/lib/ui/LegacyEmbeddedWalletExport/index.d.ts

@@ -0,0 +1 @@
+export { LegacyEmbeddedWalletExport, type LegacyEmbeddedWalletExportProps, } from './LegacyEmbeddedWalletExport';

package/src/lib/ui/LegacyWalletExportSheet/LegacyWalletExportSheet.d.ts

@@ -0,0 +1,17 @@
+import { FC } from 'react';
+import { Wallet, WalletConnectorCore } from '@dynamic-labs/wallet-connector-core';
+export type LegacyWalletExportSheetProps = {
+    wallet: Wallet<WalletConnectorCore.WalletConnector>;
+    onClose: () => void;
+};
+/**
+ * Visible export sheet for a legacy Turnkey wallet.
+ *
+ * The exported private key lives inside a cross-origin Turnkey iframe that
+ * native code cannot read, so on React Native it must be surfaced inside the
+ * webview for the user to copy and paste back into the headless-migration
+ * screen. This wraps the shared `LegacyEmbeddedWalletExport` in a presentable
+ * overlay + close button so consumers (e.g. the webview-controller) render it
+ * directly instead of hand-rolling the chrome.
+ */
+export declare const LegacyWalletExportSheet: FC<LegacyWalletExportSheetProps>;

package/src/lib/ui/LegacyWalletExportSheet/LegacyWalletExportSheet.js

@@ -0,0 +1,60 @@
+'use client'
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { LegacyEmbeddedWalletExport } from '../LegacyEmbeddedWalletExport/LegacyEmbeddedWalletExport.js';
+
+const overlayStyle = {
+    alignItems: 'center',
+    background: 'var(--dynamic-overlay, rgba(0, 0, 0, 0.5))',
+    display: 'flex',
+    inset: 0,
+    justifyContent: 'center',
+    padding: 16,
+    position: 'fixed',
+    zIndex: 2147483647,
+};
+const sheetStyle = {
+    background: 'var(--dynamic-base-1, #ffffff)',
+    borderRadius: 16,
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 16,
+    maxWidth: 420,
+    padding: 24,
+    width: '100%',
+};
+const titleStyle = {
+    color: 'var(--dynamic-text-primary, #0a0a0a)',
+    fontSize: 18,
+    fontWeight: 600,
+    margin: 0,
+};
+const descriptionStyle = {
+    color: 'var(--dynamic-text-secondary, #6b6b6b)',
+    fontSize: 14,
+    margin: 0,
+};
+const closeButtonStyle = {
+    background: 'var(--dynamic-base-3, #f5f5f5)',
+    border: 'none',
+    borderRadius: 8,
+    color: 'var(--dynamic-text-primary, #0a0a0a)',
+    cursor: 'pointer',
+    fontSize: 16,
+    fontWeight: 600,
+    padding: '12px 16px',
+    width: '100%',
+};
+/**
+ * Visible export sheet for a legacy Turnkey wallet.
+ *
+ * The exported private key lives inside a cross-origin Turnkey iframe that
+ * native code cannot read, so on React Native it must be surfaced inside the
+ * webview for the user to copy and paste back into the headless-migration
+ * screen. This wraps the shared `LegacyEmbeddedWalletExport` in a presentable
+ * overlay + close button so consumers (e.g. the webview-controller) render it
+ * directly instead of hand-rolling the chrome.
+ */
+const LegacyWalletExportSheet = ({ wallet, onClose, }) => (jsx("div", { style: overlayStyle, "data-testid": 'legacy-wallet-export-sheet', children: jsxs("div", { style: sheetStyle, children: [jsx("p", { style: titleStyle, children: "Export private key" }), jsx("p", { style: descriptionStyle, children: "Copy the private key below, then paste it back into the app to upgrade this wallet to Dynamic WaaS." }), jsx(LegacyEmbeddedWalletExport, { wallet: wallet }), jsx("button", { type: 'button', style: closeButtonStyle, onClick: onClose, "data-testid": 'legacy-wallet-export-close-btn', children: "Done" })] }) }));
+
+export { LegacyWalletExportSheet };

package/src/lib/ui/LegacyWalletExportSheet/index.d.ts

@@ -0,0 +1 @@
+export { LegacyWalletExportSheet, type LegacyWalletExportSheetProps, } from './LegacyWalletExportSheet';

package/src/lib/ui/LegacyWalletMigrationContext/LegacyWalletMigrationContext.d.ts

@@ -0,0 +1,42 @@
+import { FC, ReactNode } from 'react';
+import { Wallet, WalletConnectorCore } from '@dynamic-labs/wallet-connector-core';
+import { type LegacyWalletMigrationOnUpgrade, type LegacyWalletMigrationStep } from '../LegacyWalletMigrationModal';
+type StartUpgradeArgs = {
+    wallets?: Wallet<WalletConnectorCore.WalletConnector>[];
+    onComplete?: () => void;
+};
+export type LegacyWalletMigrationContextType = {
+    isOpen: boolean;
+    step: LegacyWalletMigrationStep;
+    startUpgrade: (args?: StartUpgradeArgs) => void;
+    close: () => void;
+    goToStep: (step: LegacyWalletMigrationStep) => void;
+};
+export declare const LegacyWalletMigrationContext: import("react").Context<LegacyWalletMigrationContextType | undefined>;
+export type LegacyWalletMigrationProviderProps = {
+    children: ReactNode;
+    /**
+     * Handler that performs the actual upgrade for a single legacy wallet.
+     * Defaults to `useUpgradeToDynamicWaas().upgradeToDynamicWaas`, which is
+     * what virtually every consumer wants — only override to customize
+     * post-upgrade restore behavior or to inject test stubs.
+     */
+    onUpgrade?: LegacyWalletMigrationOnUpgrade;
+    /**
+     * Controls whether the migration modal auto-opens when a legacy V1/V2
+     * Turnkey wallet is detected on the current user.
+     *
+     * When `true` (default), the modal opens automatically the first time a
+     * legacy wallet is observed — this is the standard "UI path" where the
+     * provider owns the migration UX end-to-end.
+     *
+     * Set to `false` for headless consumers that want to drive the upgrade
+     * flow themselves (e.g. React Native apps using their own native UI).
+     * The provider still registers itself so `useEnforceLegacyMigrationProvider`
+     * does not throw, and `startUpgrade()` can still be called manually.
+     */
+    autoOpen?: boolean;
+};
+export declare const LegacyWalletMigrationProvider: FC<LegacyWalletMigrationProviderProps>;
+export declare const useLegacyWalletMigration: () => LegacyWalletMigrationContextType;
+export {};

package/src/lib/ui/LegacyWalletMigrationContext/LegacyWalletMigrationContext.js

@@ -0,0 +1,109 @@
+'use client'
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { createContext, useState, useRef, useEffect, useCallback, useMemo, useContext } from 'react';
+import { EmbeddedWalletVersionEnum } from '@dynamic-labs/sdk-api-core';
+import { useProjectSettings, setLegacyMigrationProviderMounted } from '@dynamic-labs/sdk-react-core';
+import { logger } from '@dynamic-labs/wallet-connector-core';
+import { useLegacyWalletsToMigrate } from '../../useLegacyWalletsToMigrate/useLegacyWalletsToMigrate.js';
+import { useUpgradeToDynamicWaas } from '../../useUpgradeToDynamicWaas/useUpgradeToDynamicWaas.js';
+import { LegacyWalletMigrationModal } from '../LegacyWalletMigrationModal/LegacyWalletMigrationModal.js';
+import { LegacyWalletMigrationRecoveryProvider } from '../LegacyWalletMigrationRecoveryContext/LegacyWalletMigrationRecoveryContext.js';
+
+const LegacyWalletMigrationContext = createContext(undefined);
+const CLOSED_STATE = { open: false, step: 'select' };
+const LegacyWalletMigrationProvider = ({ children, onUpgrade, autoOpen = true }) => {
+    var _a, _b;
+    const [state, setState] = useState(CLOSED_STATE);
+    const legacyWallets = useLegacyWalletsToMigrate();
+    const projectSettings = useProjectSettings();
+    const hasAutoOpenedRef = useRef(false);
+    const { upgradeToDynamicWaas } = useUpgradeToDynamicWaas();
+    const effectiveOnUpgrade = onUpgrade !== null && onUpgrade !== void 0 ? onUpgrade : upgradeToDynamicWaas;
+    const isV3EmbeddedWalletEnabled = ((_b = (_a = projectSettings === null || projectSettings === void 0 ? void 0 : projectSettings.sdk) === null || _a === void 0 ? void 0 : _a.embeddedWallets) === null || _b === void 0 ? void 0 : _b.defaultWalletVersion) ===
+        EmbeddedWalletVersionEnum.V3;
+    // Advertise to sdk-react-core that the migration provider is mounted so
+    // its `useEnforceLegacyMigrationProvider` does not throw when a legacy
+    // Turnkey wallet is loaded.
+    useEffect(() => {
+        setLegacyMigrationProviderMounted(true);
+        return () => setLegacyMigrationProviderMounted(false);
+    }, []);
+    const startUpgrade = useCallback((args) => {
+        var _a;
+        setState({
+            onComplete: args === null || args === void 0 ? void 0 : args.onComplete,
+            open: true,
+            step: 'select',
+            // Default to the auto-detected legacy wallets so consumers calling
+            // `startUpgrade()` without arguments don't have to also wire
+            // `useLegacyWalletsToMigrate()` themselves.
+            wallets: (_a = args === null || args === void 0 ? void 0 : args.wallets) !== null && _a !== void 0 ? _a : legacyWallets,
+        });
+    }, [legacyWallets]);
+    // Auto-open the migration modal the first time we observe a legacy Turnkey
+    // wallet on the user. Legacy wallets have no supported runtime path other
+    // than migration, so we force the flow open without requiring the consumer
+    // to wire a trigger. Once `hasAutoOpenedRef` is set, we do not re-open after
+    // the user dismisses — the customer's app may still call `startUpgrade()`
+    // manually to re-trigger.
+    //
+    // We set the ref *before* the `state.open` short-circuit so that if the
+    // modal is already open when legacy wallets first appear (e.g. the consumer
+    // called `startUpgrade` directly), we still mark the detection as handled
+    // and don't fire again when the user closes.
+    //
+    // We also gate the auto-open on the project having V3 embedded wallets
+    // enabled — the migration upgrades to V3 WaaS via backend API calls that
+    // require V3 to be the configured default. Without that, the modal would
+    // open into an unrecoverable flow, so we surface the misconfig in the
+    // console and skip auto-opening.
+    useEffect(() => {
+        if (!autoOpen)
+            return;
+        if (legacyWallets.length === 0) {
+            hasAutoOpenedRef.current = false;
+            return;
+        }
+        if (hasAutoOpenedRef.current)
+            return;
+        if (!isV3EmbeddedWalletEnabled) {
+            logger.error('Legacy embedded wallet detected, but `defaultWalletVersion` is not V3 in project settings. ' +
+                'Migration requires V3 to be the configured default. Skipping auto-open of the migration modal.');
+            hasAutoOpenedRef.current = true;
+            return;
+        }
+        hasAutoOpenedRef.current = true;
+        if (state.open)
+            return;
+        startUpgrade();
+    }, [
+        autoOpen,
+        legacyWallets,
+        state.open,
+        startUpgrade,
+        isV3EmbeddedWalletEnabled,
+    ]);
+    const close = useCallback(() => {
+        setState(CLOSED_STATE);
+    }, []);
+    const goToStep = useCallback((step) => {
+        setState((previous) => (Object.assign(Object.assign({}, previous), { step })));
+    }, []);
+    const value = useMemo(() => ({
+        close,
+        goToStep,
+        isOpen: state.open,
+        startUpgrade,
+        step: state.step,
+    }), [close, goToStep, startUpgrade, state.open, state.step]);
+    return (jsxs(LegacyWalletMigrationContext.Provider, { value: value, children: [children, jsx(LegacyWalletMigrationRecoveryProvider, { children: jsx(LegacyWalletMigrationModal, { open: state.open, step: state.step, onClose: close, onStepChange: goToStep, onComplete: state.onComplete, onUpgrade: effectiveOnUpgrade, wallets: state.wallets }) })] }));
+};
+const useLegacyWalletMigration = () => {
+    const context = useContext(LegacyWalletMigrationContext);
+    if (context === undefined) {
+        throw new Error('useLegacyWalletMigration must be used inside a LegacyWalletMigrationProvider.');
+    }
+    return context;
+};
+
+export { LegacyWalletMigrationContext, LegacyWalletMigrationProvider, useLegacyWalletMigration };

package/src/lib/ui/LegacyWalletMigrationContext/index.d.ts

@@ -0,0 +1 @@
+export { LegacyWalletMigrationContext, LegacyWalletMigrationProvider, useLegacyWalletMigration, type LegacyWalletMigrationContextType, type LegacyWalletMigrationProviderProps, } from './LegacyWalletMigrationContext';

package/src/lib/ui/LegacyWalletMigrationModal/LegacyWalletMigrationModal.d.ts

@@ -0,0 +1,15 @@
+import { FC } from 'react';
+import { Wallet, WalletConnectorCore } from '@dynamic-labs/wallet-connector-core';
+import { type WalletUpgradeFlowViewOnUpgradeArgs } from '../WalletUpgradeFlowView';
+export type LegacyWalletMigrationStep = 'select' | 'upgrade' | 'complete' | 'passkey-recovery-add-email' | 'passkey-recovery-bundle' | 'passkey-recovery-complete' | 'embedded-wallet-auth-choice';
+export type LegacyWalletMigrationOnUpgrade = (args: WalletUpgradeFlowViewOnUpgradeArgs) => Promise<void>;
+export type LegacyWalletMigrationModalProps = {
+    open: boolean;
+    step: LegacyWalletMigrationStep;
+    onClose: () => void;
+    onStepChange: (step: LegacyWalletMigrationStep) => void;
+    onComplete?: () => void;
+    onUpgrade: LegacyWalletMigrationOnUpgrade;
+    wallets?: Wallet<WalletConnectorCore.WalletConnector>[];
+};
+export declare const LegacyWalletMigrationModal: FC<LegacyWalletMigrationModalProps>;