decane-connect-kit 1.0.3 → 2.0.1

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import * as _simplewebauthn_browser from '@simplewebauthn/browser';
 import React, { ReactNode } from 'react';
 
 type ChainType = "evm" | "solana" | "tron" | "bitcoin";
@@ -133,14 +134,6 @@ interface BitcoinProvider {
 
 declare function createDecane(config?: DecaneConfig): DecaneProvider;
 
-interface PhraseGenerationResult {
-    phrase: string;
-    challenge: Array<{
-        position: number;
-        expected: string;
-    }>;
-}
-
 declare class ApiClient {
     private readonly baseUrl;
     private readonly apiKey;
@@ -162,6 +155,8 @@ declare class ApiClient {
         evmAddress: string;
         solanaAddress: string;
     }): Promise<void>;
+    getWebAuthnRegisterOptions(jwt: string, rpId: string, rpName: string): Promise<_simplewebauthn_browser.PublicKeyCredentialCreationOptionsJSON>;
+    postWebAuthnRegister(jwt: string, response: _simplewebauthn_browser.RegistrationResponseJSON, origin: string): Promise<void>;
     revoke(jwt: string): Promise<void>;
     hasRecoveryBackup(jwt: string): Promise<boolean>;
     getRecoveryBackup(jwt: string): Promise<{
@@ -180,7 +175,14 @@ declare class ApiClient {
         prfSalt: Uint8Array;
     }): Promise<void>;
     deleteRecoveryBackup(jwt: string): Promise<void>;
-    markPhraseSaved(jwt: string): Promise<void>;
+    markRecoveryShareSaved(jwt: string): Promise<void>;
+    getRecoveryStatus(jwt: string): Promise<{
+        hasRecoveryShare: boolean;
+        savedAt: string | null;
+        nagged: boolean;
+        shareSetVersion: number;
+    }>;
+    dismissRecoveryNag(jwt: string): Promise<void>;
 }
 
 type RecoveryProgress = {
@@ -189,11 +191,57 @@ type RecoveryProgress = {
     type: 'passkey-failed';
     reason: string;
 } | {
-    type: 'phrase-prompt';
+    type: 'recovery-file-prompt';
+} | {
+    type: 'password-prompt';
+    passwordHint: string | null;
 } | {
-    type: 'phrase-verifying';
+    type: 'recovery-verifying';
+} | {
+    type: 'rotated';
+    shareSetVersion: number;
 };
 
+interface RecoveryShareFile {
+    version: number;
+    type: 'decane-recovery-share';
+    shareSetVersion: number;
+    kdf: 'pbkdf2-sha256';
+    kdfParams: {
+        iterations: number;
+        salt: string;
+    };
+    cipher: 'aes-256-gcm';
+    iv: string;
+    ciphertext: string;
+    addresses: {
+        evm: string;
+        solana: string;
+    };
+    passwordHint: string | null;
+    createdAt: string;
+}
+
+interface PortableBackup {
+    version: number;
+    type: 'decane-portable-backup';
+    shareSetVersion: number;
+    kdf: 'pbkdf2-sha256';
+    kdfParams: {
+        iterations: number;
+        salt: string;
+    };
+    cipher: 'aes-256-gcm';
+    iv: string;
+    ciphertext: string;
+    addresses: {
+        evm: string;
+        solana: string;
+    };
+    passwordHint: string | null;
+    createdAt: string;
+}
+
 type Chain = `evm:${number}` | `solana:${'mainnet' | 'devnet'}`;
 interface DecaneConnectConfig {
     apiKey: string;
@@ -206,18 +254,36 @@ interface DecaneConnectConfig {
     rpName?: string;
     rpcUrls?: Record<string, string>;
     teeUrl?: string;
-    /** Offer phrase generation during signup. Default true. */
-    offerPhraseAtSignup?: boolean;
-    /** Show the phrase to the user; return their confirmation answers. */
-    onPhraseGenerated?: (result: PhraseGenerationResult) => Promise<{
-        userConfirmed: boolean;
-        userAnswers: Array<{
-            position: number;
-            word: string;
-        }>;
+    /** Offer to save a recovery-share file at signup. Default true. Never blocks onboarding. */
+    offerRecoveryAtSignup?: boolean;
+    /** Ask the user whether they want a recovery share and, if so, a password for it. */
+    onRecoveryShareOffer?: (addresses: {
+        evmAddress: string;
+        solanaAddress: string;
+    }) => Promise<{
+        wants: boolean;
+        password: string;
+        passwordHint?: string;
+    }>;
+    /** Hand the built file + suggested filename to the dApp, which owns the actual download. */
+    onRecoveryFileReady?: (file: RecoveryShareFile, filename: string) => Promise<void>;
+    /** Prompt for a recovery-share file (and its password) during Flow B. Return null to cancel. */
+    promptForRecoveryFile?: () => Promise<{
+        value: unknown;
+        getPassword: () => Promise<string | null>;
+    } | null>;
+    /**
+     * Every successful recovery/rotation invalidates the previous recovery
+     * file — this MUST prompt for a new password and block progress until the
+     * dApp confirms the user saved the new file (see MIGRATE_SSS_RECOVERY.md §10).
+     */
+    onRecoveryRotated?: (addresses: {
+        evmAddress: string;
+        solanaAddress: string;
+    }) => Promise<{
+        password: string;
+        passwordHint?: string;
     }>;
-    /** Prompt for a phrase during recovery. Return null to cancel. */
-    promptForRecoveryPhrase?: () => Promise<string | null>;
     /** Recovery stage callbacks, for dApp UI. */
     onRecoveryProgress?: (event: RecoveryProgress) => void;
 }
@@ -250,6 +316,12 @@ interface DecaneConnect {
     verifyEmailCode(email: string, code: string): Promise<ConnectResult>;
     unlock(): Promise<void>;
     isUnlocked(): boolean;
+    /**
+     * True when the user's identity is known from a previous visit but there is
+     * no live session, so unlock() cannot succeed and they must sign in again.
+     * Check this before offering an "Unlock" action.
+     */
+    needsReconnect(): boolean;
     sessionExpiresAt(): number | null;
     signMessage(req: SignMessageRequest): Promise<string>;
     sendTransaction(req: SendTransactionRequest): Promise<string>;
@@ -259,16 +331,32 @@ interface DecaneConnect {
         evm?: string;
         solana?: string;
     } | null;
-    /** Generate a recovery phrase. Re-prompts for unlock; does not cache the share. */
-    generateRecoveryPhrase(): Promise<PhraseGenerationResult>;
-    /** Record that the user confirmed they saved the phrase. */
-    markPhraseSaved(challenge: Array<{
-        position: number;
-        expected: string;
-    }>, userAnswers: Array<{
-        position: number;
-        word: string;
-    }>): Promise<boolean>;
+    /**
+     * Voluntary share rotation — after a suspected device compromise, or just
+     * to invalidate an old recovery file. Requires a fresh WebAuthn assertion.
+     * Returns the new recovery-share file (the caller still owns delivering it
+     * to the user — this does not download anything itself).
+     */
+    rotateShares(opts: {
+        password: string;
+        passwordHint?: string;
+    }): Promise<RecoveryShareFile>;
+    /**
+     * The two-share bearer portable backup (device + recovery). This file plus
+     * its password gives complete control of the wallet — see the mandatory
+     * warning-screen requirements in MIGRATE_SSS_RECOVERY.md §10. Requires a
+     * fresh WebAuthn assertion and rotates the share set on every export.
+     */
+    exportPortableBackup(opts: {
+        password: string;
+        passwordHint?: string;
+    }): Promise<PortableBackup>;
+    /** Whether the user has ever saved a recovery-share file (UX flag only — Decane never stores the share). */
+    hasRecoveryShare(): Promise<boolean>;
+    /** True at most once per account: no recovery share saved, never nagged, wallet holds value. */
+    shouldPromptRecovery(): Promise<boolean>;
+    /** Call regardless of the user's answer — the recovery nag fires once, ever. */
+    dismissRecoveryPrompt(): Promise<void>;
     /** Whether a wrapped-share backup exists on the server. */
     hasBackup(): Promise<boolean>;
     /** Delete the server-side backup. Disables Flow A recovery. */
@@ -319,6 +407,22 @@ declare class SessionExpiredError extends DecaneConnectError {
 declare class UnlockRequiredError extends DecaneConnectError {
     constructor();
 }
+/**
+ * unlock() was called after a page reload (or any other loss of the in-memory
+ * auth state). We still know *who* the user is — their identity and addresses
+ * are persisted — but unlock() needs a live JWT to open a TEE session, and
+ * JWTs are deliberately never persisted. So there is no unlock() that can
+ * succeed here; the user has to re-authenticate.
+ *
+ * This is its own error type rather than a generic CallSequenceError because
+ * it is a *routing* signal, not a programming mistake: the correct response is
+ * to show the sign-in UI, which callers can only do reliably if they can tell
+ * this case apart from "you never called connect()". Prefer checking
+ * needsReconnect() up front so this never has to be caught at all.
+ */
+declare class ReconnectRequiredError extends DecaneConnectError {
+    constructor();
+}
 declare class UserCancelledError extends DecaneConnectError {
     constructor();
 }
@@ -349,7 +453,16 @@ declare class AttestationError extends DecaneConnectError {
 declare class RecoveryFailedError extends DecaneConnectError {
     constructor(reason: string);
 }
-declare class InvalidPhraseError extends DecaneConnectError {
+declare class InvalidRecoveryFileError extends DecaneConnectError {
+    constructor();
+}
+declare class WrongPasswordError extends DecaneConnectError {
+    constructor();
+}
+declare class RecoveryWalletMismatchError extends DecaneConnectError {
+    constructor();
+}
+declare class ExportNotAuthorizedError extends DecaneConnectError {
     constructor();
 }
 
@@ -467,6 +580,16 @@ interface SocialAuthState {
     isNewUser: boolean;
     isUnlocked: boolean;
     sessionExpiresAt: number | null;
+    /**
+     * True when `addresses` came from persisted (localStorage) identity only,
+     * with no live session. This is NOT the same as "locked" — every unlock()
+     * requires a fresh, valid JWT to open a TEE session, and JWTs are
+     * deliberately never persisted (short-lived, security-sensitive), so
+     * there is no legitimate "just unlock" path in this state. A consumer
+     * should route this into a full reconnect (connectWithGoogle() /
+     * connectWithEmail()), not unlock() — which will always throw here.
+     */
+    needsReconnect: boolean;
 }
 interface DecaneKitProps {
     config?: DecaneConfig;
@@ -481,8 +604,24 @@ interface SocialWalletModalProps {
     socialAuth: SocialAuthState;
     onUnlock: () => Promise<void>;
     onDisconnect: () => Promise<void>;
+    onGoogleSignIn: () => Promise<void>;
+    onEmailStart: (email: string) => Promise<{
+        codeRequired: true;
+    }>;
+    onEmailVerify: (email: string, code: string) => Promise<void>;
+    authMethods?: Array<"google" | "email">;
+    onRotateShares: (opts: {
+        password: string;
+        passwordHint?: string;
+    }) => Promise<RecoveryShareFile>;
+    onExportPortableBackup: (opts: {
+        password: string;
+        passwordHint?: string;
+    }) => Promise<PortableBackup>;
+    rpcUrls?: Record<string, string>;
+    chains?: string[];
 }
-declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, }: SocialWalletModalProps): React.ReactPortal | null;
+declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, onGoogleSignIn, onEmailStart, onEmailVerify, authMethods, onRotateShares, onExportPortableBackup, rpcUrls, chains, }: SocialWalletModalProps): React.ReactPortal | null;
 
 declare function useSocialAuth(): {
     isConnected: boolean;
@@ -493,6 +632,7 @@ declare function useSocialAuth(): {
         solana?: string;
     } | null;
     sessionExpiresAt: number | null;
+    needsReconnect: boolean;
     googleLoading: boolean;
     emailLoading: boolean;
     error: string | null;
@@ -514,6 +654,7 @@ declare function useSocialWallet(): {
         solana?: string;
     } | null;
     sessionExpiresAt: number | null;
+    needsReconnect: boolean;
     modalOpen: boolean;
     openModal: () => void;
     closeModal: () => void;
@@ -529,6 +670,17 @@ declare function useSocialWallet(): {
         gasPrice?: bigint;
     }) => Promise<string>;
     signSolanaTransaction: (tx: Uint8Array) => Promise<Uint8Array<ArrayBufferLike>>;
+    rotateShares: (opts: {
+        password: string;
+        passwordHint?: string;
+    }) => Promise<RecoveryShareFile>;
+    exportPortableBackup: (opts: {
+        password: string;
+        passwordHint?: string;
+    }) => Promise<PortableBackup>;
+    hasRecoveryShare: () => Promise<boolean>;
+    shouldPromptRecovery: () => Promise<boolean>;
+    dismissRecoveryPrompt: () => Promise<void>;
     loading: boolean;
     error: string | null;
     clearError: () => void;
@@ -605,4 +757,4 @@ declare function useSignTypedData(): {
     reset: () => void;
 };
 
-export { type ActiveSession, AttestationError, type AuthResult, BUILT_IN_CHAINS, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, type DecaneProvider, InvalidApiKeyError, InvalidPhraseError, InvalidPinError, NetworkError, NewDeviceError, OriginNotAllowedError, type PhraseGenerationResult, PromptPinNotConfiguredError, RecoveryFailedError, type RecoveryProgress, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SocialAuthState, type SocialConfig, SocialWalletModal, type Theme, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UserCancelledError, WalletSelector, WebAuthnNotSupportedError, type WrappedShareMeta, createDecane, createDecaneConnect, startEmailAuth, useChainSwitch, useDecane, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialWallet, useWalletSelector, verifyEmailCode };
+export { type ActiveSession, AttestationError, type AuthResult, BUILT_IN_CHAINS, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, type DecaneProvider, ExportNotAuthorizedError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPinNotConfiguredError, ReconnectRequiredError, RecoveryFailedError, type RecoveryProgress, type RecoveryShareFile, RecoveryWalletMismatchError, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SocialAuthState, type SocialConfig, SocialWalletModal, type Theme, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UserCancelledError, WalletSelector, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, createDecane, createDecaneConnect, startEmailAuth, useChainSwitch, useDecane, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialWallet, useWalletSelector, verifyEmailCode };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import * as _simplewebauthn_browser from '@simplewebauthn/browser';
 import React, { ReactNode } from 'react';
 
 type ChainType = "evm" | "solana" | "tron" | "bitcoin";
@@ -133,14 +134,6 @@ interface BitcoinProvider {
 
 declare function createDecane(config?: DecaneConfig): DecaneProvider;
 
-interface PhraseGenerationResult {
-    phrase: string;
-    challenge: Array<{
-        position: number;
-        expected: string;
-    }>;
-}
-
 declare class ApiClient {
     private readonly baseUrl;
     private readonly apiKey;
@@ -162,6 +155,8 @@ declare class ApiClient {
         evmAddress: string;
         solanaAddress: string;
     }): Promise<void>;
+    getWebAuthnRegisterOptions(jwt: string, rpId: string, rpName: string): Promise<_simplewebauthn_browser.PublicKeyCredentialCreationOptionsJSON>;
+    postWebAuthnRegister(jwt: string, response: _simplewebauthn_browser.RegistrationResponseJSON, origin: string): Promise<void>;
     revoke(jwt: string): Promise<void>;
     hasRecoveryBackup(jwt: string): Promise<boolean>;
     getRecoveryBackup(jwt: string): Promise<{
@@ -180,7 +175,14 @@ declare class ApiClient {
         prfSalt: Uint8Array;
     }): Promise<void>;
     deleteRecoveryBackup(jwt: string): Promise<void>;
-    markPhraseSaved(jwt: string): Promise<void>;
+    markRecoveryShareSaved(jwt: string): Promise<void>;
+    getRecoveryStatus(jwt: string): Promise<{
+        hasRecoveryShare: boolean;
+        savedAt: string | null;
+        nagged: boolean;
+        shareSetVersion: number;
+    }>;
+    dismissRecoveryNag(jwt: string): Promise<void>;
 }
 
 type RecoveryProgress = {
@@ -189,11 +191,57 @@ type RecoveryProgress = {
     type: 'passkey-failed';
     reason: string;
 } | {
-    type: 'phrase-prompt';
+    type: 'recovery-file-prompt';
+} | {
+    type: 'password-prompt';
+    passwordHint: string | null;
 } | {
-    type: 'phrase-verifying';
+    type: 'recovery-verifying';
+} | {
+    type: 'rotated';
+    shareSetVersion: number;
 };
 
+interface RecoveryShareFile {
+    version: number;
+    type: 'decane-recovery-share';
+    shareSetVersion: number;
+    kdf: 'pbkdf2-sha256';
+    kdfParams: {
+        iterations: number;
+        salt: string;
+    };
+    cipher: 'aes-256-gcm';
+    iv: string;
+    ciphertext: string;
+    addresses: {
+        evm: string;
+        solana: string;
+    };
+    passwordHint: string | null;
+    createdAt: string;
+}
+
+interface PortableBackup {
+    version: number;
+    type: 'decane-portable-backup';
+    shareSetVersion: number;
+    kdf: 'pbkdf2-sha256';
+    kdfParams: {
+        iterations: number;
+        salt: string;
+    };
+    cipher: 'aes-256-gcm';
+    iv: string;
+    ciphertext: string;
+    addresses: {
+        evm: string;
+        solana: string;
+    };
+    passwordHint: string | null;
+    createdAt: string;
+}
+
 type Chain = `evm:${number}` | `solana:${'mainnet' | 'devnet'}`;
 interface DecaneConnectConfig {
     apiKey: string;
@@ -206,18 +254,36 @@ interface DecaneConnectConfig {
     rpName?: string;
     rpcUrls?: Record<string, string>;
     teeUrl?: string;
-    /** Offer phrase generation during signup. Default true. */
-    offerPhraseAtSignup?: boolean;
-    /** Show the phrase to the user; return their confirmation answers. */
-    onPhraseGenerated?: (result: PhraseGenerationResult) => Promise<{
-        userConfirmed: boolean;
-        userAnswers: Array<{
-            position: number;
-            word: string;
-        }>;
+    /** Offer to save a recovery-share file at signup. Default true. Never blocks onboarding. */
+    offerRecoveryAtSignup?: boolean;
+    /** Ask the user whether they want a recovery share and, if so, a password for it. */
+    onRecoveryShareOffer?: (addresses: {
+        evmAddress: string;
+        solanaAddress: string;
+    }) => Promise<{
+        wants: boolean;
+        password: string;
+        passwordHint?: string;
+    }>;
+    /** Hand the built file + suggested filename to the dApp, which owns the actual download. */
+    onRecoveryFileReady?: (file: RecoveryShareFile, filename: string) => Promise<void>;
+    /** Prompt for a recovery-share file (and its password) during Flow B. Return null to cancel. */
+    promptForRecoveryFile?: () => Promise<{
+        value: unknown;
+        getPassword: () => Promise<string | null>;
+    } | null>;
+    /**
+     * Every successful recovery/rotation invalidates the previous recovery
+     * file — this MUST prompt for a new password and block progress until the
+     * dApp confirms the user saved the new file (see MIGRATE_SSS_RECOVERY.md §10).
+     */
+    onRecoveryRotated?: (addresses: {
+        evmAddress: string;
+        solanaAddress: string;
+    }) => Promise<{
+        password: string;
+        passwordHint?: string;
     }>;
-    /** Prompt for a phrase during recovery. Return null to cancel. */
-    promptForRecoveryPhrase?: () => Promise<string | null>;
     /** Recovery stage callbacks, for dApp UI. */
     onRecoveryProgress?: (event: RecoveryProgress) => void;
 }
@@ -250,6 +316,12 @@ interface DecaneConnect {
     verifyEmailCode(email: string, code: string): Promise<ConnectResult>;
     unlock(): Promise<void>;
     isUnlocked(): boolean;
+    /**
+     * True when the user's identity is known from a previous visit but there is
+     * no live session, so unlock() cannot succeed and they must sign in again.
+     * Check this before offering an "Unlock" action.
+     */
+    needsReconnect(): boolean;
     sessionExpiresAt(): number | null;
     signMessage(req: SignMessageRequest): Promise<string>;
     sendTransaction(req: SendTransactionRequest): Promise<string>;
@@ -259,16 +331,32 @@ interface DecaneConnect {
         evm?: string;
         solana?: string;
     } | null;
-    /** Generate a recovery phrase. Re-prompts for unlock; does not cache the share. */
-    generateRecoveryPhrase(): Promise<PhraseGenerationResult>;
-    /** Record that the user confirmed they saved the phrase. */
-    markPhraseSaved(challenge: Array<{
-        position: number;
-        expected: string;
-    }>, userAnswers: Array<{
-        position: number;
-        word: string;
-    }>): Promise<boolean>;
+    /**
+     * Voluntary share rotation — after a suspected device compromise, or just
+     * to invalidate an old recovery file. Requires a fresh WebAuthn assertion.
+     * Returns the new recovery-share file (the caller still owns delivering it
+     * to the user — this does not download anything itself).
+     */
+    rotateShares(opts: {
+        password: string;
+        passwordHint?: string;
+    }): Promise<RecoveryShareFile>;
+    /**
+     * The two-share bearer portable backup (device + recovery). This file plus
+     * its password gives complete control of the wallet — see the mandatory
+     * warning-screen requirements in MIGRATE_SSS_RECOVERY.md §10. Requires a
+     * fresh WebAuthn assertion and rotates the share set on every export.
+     */
+    exportPortableBackup(opts: {
+        password: string;
+        passwordHint?: string;
+    }): Promise<PortableBackup>;
+    /** Whether the user has ever saved a recovery-share file (UX flag only — Decane never stores the share). */
+    hasRecoveryShare(): Promise<boolean>;
+    /** True at most once per account: no recovery share saved, never nagged, wallet holds value. */
+    shouldPromptRecovery(): Promise<boolean>;
+    /** Call regardless of the user's answer — the recovery nag fires once, ever. */
+    dismissRecoveryPrompt(): Promise<void>;
     /** Whether a wrapped-share backup exists on the server. */
     hasBackup(): Promise<boolean>;
     /** Delete the server-side backup. Disables Flow A recovery. */
@@ -319,6 +407,22 @@ declare class SessionExpiredError extends DecaneConnectError {
 declare class UnlockRequiredError extends DecaneConnectError {
     constructor();
 }
+/**
+ * unlock() was called after a page reload (or any other loss of the in-memory
+ * auth state). We still know *who* the user is — their identity and addresses
+ * are persisted — but unlock() needs a live JWT to open a TEE session, and
+ * JWTs are deliberately never persisted. So there is no unlock() that can
+ * succeed here; the user has to re-authenticate.
+ *
+ * This is its own error type rather than a generic CallSequenceError because
+ * it is a *routing* signal, not a programming mistake: the correct response is
+ * to show the sign-in UI, which callers can only do reliably if they can tell
+ * this case apart from "you never called connect()". Prefer checking
+ * needsReconnect() up front so this never has to be caught at all.
+ */
+declare class ReconnectRequiredError extends DecaneConnectError {
+    constructor();
+}
 declare class UserCancelledError extends DecaneConnectError {
     constructor();
 }
@@ -349,7 +453,16 @@ declare class AttestationError extends DecaneConnectError {
 declare class RecoveryFailedError extends DecaneConnectError {
     constructor(reason: string);
 }
-declare class InvalidPhraseError extends DecaneConnectError {
+declare class InvalidRecoveryFileError extends DecaneConnectError {
+    constructor();
+}
+declare class WrongPasswordError extends DecaneConnectError {
+    constructor();
+}
+declare class RecoveryWalletMismatchError extends DecaneConnectError {
+    constructor();
+}
+declare class ExportNotAuthorizedError extends DecaneConnectError {
     constructor();
 }
 
@@ -467,6 +580,16 @@ interface SocialAuthState {
     isNewUser: boolean;
     isUnlocked: boolean;
     sessionExpiresAt: number | null;
+    /**
+     * True when `addresses` came from persisted (localStorage) identity only,
+     * with no live session. This is NOT the same as "locked" — every unlock()
+     * requires a fresh, valid JWT to open a TEE session, and JWTs are
+     * deliberately never persisted (short-lived, security-sensitive), so
+     * there is no legitimate "just unlock" path in this state. A consumer
+     * should route this into a full reconnect (connectWithGoogle() /
+     * connectWithEmail()), not unlock() — which will always throw here.
+     */
+    needsReconnect: boolean;
 }
 interface DecaneKitProps {
     config?: DecaneConfig;
@@ -481,8 +604,24 @@ interface SocialWalletModalProps {
     socialAuth: SocialAuthState;
     onUnlock: () => Promise<void>;
     onDisconnect: () => Promise<void>;
+    onGoogleSignIn: () => Promise<void>;
+    onEmailStart: (email: string) => Promise<{
+        codeRequired: true;
+    }>;
+    onEmailVerify: (email: string, code: string) => Promise<void>;
+    authMethods?: Array<"google" | "email">;
+    onRotateShares: (opts: {
+        password: string;
+        passwordHint?: string;
+    }) => Promise<RecoveryShareFile>;
+    onExportPortableBackup: (opts: {
+        password: string;
+        passwordHint?: string;
+    }) => Promise<PortableBackup>;
+    rpcUrls?: Record<string, string>;
+    chains?: string[];
 }
-declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, }: SocialWalletModalProps): React.ReactPortal | null;
+declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, onGoogleSignIn, onEmailStart, onEmailVerify, authMethods, onRotateShares, onExportPortableBackup, rpcUrls, chains, }: SocialWalletModalProps): React.ReactPortal | null;
 
 declare function useSocialAuth(): {
     isConnected: boolean;
@@ -493,6 +632,7 @@ declare function useSocialAuth(): {
         solana?: string;
     } | null;
     sessionExpiresAt: number | null;
+    needsReconnect: boolean;
     googleLoading: boolean;
     emailLoading: boolean;
     error: string | null;
@@ -514,6 +654,7 @@ declare function useSocialWallet(): {
         solana?: string;
     } | null;
     sessionExpiresAt: number | null;
+    needsReconnect: boolean;
     modalOpen: boolean;
     openModal: () => void;
     closeModal: () => void;
@@ -529,6 +670,17 @@ declare function useSocialWallet(): {
         gasPrice?: bigint;
     }) => Promise<string>;
     signSolanaTransaction: (tx: Uint8Array) => Promise<Uint8Array<ArrayBufferLike>>;
+    rotateShares: (opts: {
+        password: string;
+        passwordHint?: string;
+    }) => Promise<RecoveryShareFile>;
+    exportPortableBackup: (opts: {
+        password: string;
+        passwordHint?: string;
+    }) => Promise<PortableBackup>;
+    hasRecoveryShare: () => Promise<boolean>;
+    shouldPromptRecovery: () => Promise<boolean>;
+    dismissRecoveryPrompt: () => Promise<void>;
     loading: boolean;
     error: string | null;
     clearError: () => void;
@@ -605,4 +757,4 @@ declare function useSignTypedData(): {
     reset: () => void;
 };
 
-export { type ActiveSession, AttestationError, type AuthResult, BUILT_IN_CHAINS, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, type DecaneProvider, InvalidApiKeyError, InvalidPhraseError, InvalidPinError, NetworkError, NewDeviceError, OriginNotAllowedError, type PhraseGenerationResult, PromptPinNotConfiguredError, RecoveryFailedError, type RecoveryProgress, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SocialAuthState, type SocialConfig, SocialWalletModal, type Theme, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UserCancelledError, WalletSelector, WebAuthnNotSupportedError, type WrappedShareMeta, createDecane, createDecaneConnect, startEmailAuth, useChainSwitch, useDecane, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialWallet, useWalletSelector, verifyEmailCode };
+export { type ActiveSession, AttestationError, type AuthResult, BUILT_IN_CHAINS, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, CallSequenceError, type Chain, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type ConnectMode, type ConnectResult, type DecaneConfig, type DecaneConnect, type DecaneConnectConfig, DecaneConnectError, DecaneError, DecaneErrorCode, DecaneKit, type DecaneProvider, ExportNotAuthorizedError, InvalidApiKeyError, InvalidPinError, InvalidRecoveryFileError, NetworkError, NewDeviceError, OriginNotAllowedError, type PortableBackup, PromptPinNotConfiguredError, ReconnectRequiredError, RecoveryFailedError, type RecoveryProgress, type RecoveryShareFile, RecoveryWalletMismatchError, type SdkEvent, type SendTransactionRequest, SessionExpiredError, ShareCorruptedError, type SignMessageRequest, type SocialAuthState, type SocialConfig, SocialWalletModal, type Theme, type TxParams, type UnifiedWalletAccount, UnlockRequiredError, UserCancelledError, WalletSelector, WebAuthnNotSupportedError, type WrappedShareMeta, WrongPasswordError, createDecane, createDecaneConnect, startEmailAuth, useChainSwitch, useDecane, useSendTransaction, useSignMessage, useSignTypedData, useSocialAuth, useSocialWallet, useWalletSelector, verifyEmailCode };