decane-connect-kit 1.0.3 → 2.0.0

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: 'phrase-verifying';
+    type: 'password-prompt';
+    passwordHint: string | null;
+} | {
+    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;
 }
@@ -259,16 +325,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. */
@@ -349,7 +431,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();
 }
 
@@ -605,4 +696,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, 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: 'phrase-verifying';
+    type: 'password-prompt';
+    passwordHint: string | null;
+} | {
+    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;
 }
@@ -259,16 +325,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. */
@@ -349,7 +431,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();
 }
 
@@ -605,4 +696,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, 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 };