decane-connect-kit 1.0.2 → 2.0.0

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";
@@ -72,12 +73,23 @@ interface DecaneProvider {
     readonly activeSession: ActiveSession | null;
     readonly activeChain: string | null;
 }
+type ConnectMode = "all" | "social" | "wallets" | "evm" | "solana" | "tron" | "evm+social" | "solana+social" | "tron+social" | "evm+tron" | "evm+tron+social";
+interface SocialConfig {
+    apiKey: string;
+    authMethods?: ("google" | "email")[];
+    promptPin?: () => Promise<string>;
+    apiBaseUrl?: string;
+    chains?: string[];
+    rpcUrls?: Record<string, string>;
+}
 interface DecaneConfig {
     chains?: ChainDescriptor[];
     supportedChainIds?: string[];
     networks?: "evm" | "solana" | "tron" | "bitcoin" | "all";
     defaultChain?: string;
     theme?: "light" | "dark" | "auto";
+    mode?: ConnectMode;
+    social?: SocialConfig;
 }
 interface EIP1193Provider {
     request(args: {
@@ -122,6 +134,316 @@ interface BitcoinProvider {
 
 declare function createDecane(config?: DecaneConfig): DecaneProvider;
 
+declare class ApiClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private _request;
+    getGoogleInitUrl(): Promise<{
+        url: string;
+    }>;
+    authEmailStart(email: string): Promise<void>;
+    authEmailVerify(email: string, code: string): Promise<AuthResult>;
+    getAddresses(jwt: string): Promise<{
+        evm: string | null;
+        solana: string | null;
+    }>;
+    putShare(jwt: string, share: {
+        ciphertext: Uint8Array;
+        iv: Uint8Array;
+        wrappedShareMeta: WrappedShareMeta;
+        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<{
+        wrappedDeviceShare: Uint8Array;
+        iv: Uint8Array;
+        unlockMethod: 'passkey';
+        credentialId: Uint8Array;
+        prfSalt: Uint8Array;
+        formatVersion: number;
+    } | null>;
+    putRecoveryBackup(jwt: string, backup: {
+        wrappedDeviceShare: Uint8Array;
+        iv: Uint8Array;
+        unlockMethod: 'passkey';
+        credentialId: Uint8Array;
+        prfSalt: Uint8Array;
+    }): Promise<void>;
+    deleteRecoveryBackup(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 = {
+    type: 'passkey-attempt';
+} | {
+    type: 'passkey-failed';
+    reason: string;
+} | {
+    type: 'recovery-file-prompt';
+} | {
+    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;
+    chains: Chain[];
+    authMethods: Array<'google' | 'email'>;
+    apiBaseUrl?: string;
+    sessionDurationMinutes?: number;
+    promptPin?: () => Promise<string>;
+    rpId?: string;
+    rpName?: string;
+    rpcUrls?: Record<string, string>;
+    teeUrl?: 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;
+    }>;
+    /** Recovery stage callbacks, for dApp UI. */
+    onRecoveryProgress?: (event: RecoveryProgress) => void;
+}
+interface ConnectResult {
+    addresses: {
+        evm?: string;
+        solana?: string;
+    };
+    isNewUser: boolean;
+}
+interface SignMessageRequest {
+    chain: Chain;
+    message: string | Uint8Array;
+}
+interface SendTransactionRequest {
+    chain: Chain;
+    to: string;
+    value?: bigint;
+    data?: string;
+    gasLimit?: bigint;
+    gasPrice?: bigint;
+}
+type SdkEvent = 'connected' | 'disconnected' | 'session-expired' | 'session-started';
+interface DecaneConnect {
+    connect(): Promise<ConnectResult>;
+    connectWithGoogle(): Promise<ConnectResult>;
+    connectWithEmail(email: string): Promise<{
+        codeRequired: true;
+    }>;
+    verifyEmailCode(email: string, code: string): Promise<ConnectResult>;
+    unlock(): Promise<void>;
+    isUnlocked(): boolean;
+    sessionExpiresAt(): number | null;
+    signMessage(req: SignMessageRequest): Promise<string>;
+    sendTransaction(req: SendTransactionRequest): Promise<string>;
+    signSolanaTransaction(tx: Uint8Array): Promise<Uint8Array>;
+    disconnect(): Promise<void>;
+    getAddresses(): {
+        evm?: string;
+        solana?: string;
+    } | null;
+    /**
+     * 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. */
+    deleteBackup(): Promise<void>;
+    on(event: SdkEvent, handler: (...args: unknown[]) => void): void;
+    off(event: SdkEvent, handler: (...args: unknown[]) => void): void;
+}
+interface WrappedShareMeta {
+    unlockMethod: 'passkey' | 'pin';
+    credentialId?: string;
+    prfSalt?: string;
+    pinSalt?: string;
+    pinIterations?: number;
+}
+interface AuthResult {
+    jwt: string;
+    isNewUser: boolean;
+    hasShare: boolean;
+    userId: string;
+}
+
+declare function createDecaneConnect(config: DecaneConnectConfig): Promise<DecaneConnect>;
+
+/**
+ * Sends a 6-digit magic-link code to the user's email.
+ * Always returns void regardless of whether the email exists (prevents enumeration).
+ */
+declare function startEmailAuth(api: ApiClient, email: string): Promise<void>;
+/**
+ * Verifies the 6-digit code and exchanges it for a JWT.
+ */
+declare function verifyEmailCode(api: ApiClient, email: string, code: string): Promise<AuthResult>;
+
+declare class DecaneConnectError extends Error {
+    code: string;
+    retryable: boolean;
+    constructor(code: string, message: string, retryable?: boolean);
+}
+declare class InvalidApiKeyError extends DecaneConnectError {
+    constructor();
+}
+declare class OriginNotAllowedError extends DecaneConnectError {
+    constructor(origin: string);
+}
+declare class SessionExpiredError extends DecaneConnectError {
+    constructor();
+}
+declare class UnlockRequiredError extends DecaneConnectError {
+    constructor();
+}
+declare class UserCancelledError extends DecaneConnectError {
+    constructor();
+}
+declare class WebAuthnNotSupportedError extends DecaneConnectError {
+    constructor();
+}
+declare class InvalidPinError extends DecaneConnectError {
+    constructor();
+}
+declare class CallSequenceError extends DecaneConnectError {
+    constructor(msg: string);
+}
+declare class NetworkError extends DecaneConnectError {
+    constructor();
+}
+declare class ShareCorruptedError extends DecaneConnectError {
+    constructor();
+}
+declare class NewDeviceError extends DecaneConnectError {
+    constructor();
+}
+declare class PromptPinNotConfiguredError extends DecaneConnectError {
+    constructor();
+}
+declare class AttestationError extends DecaneConnectError {
+    constructor(msg: string);
+}
+declare class RecoveryFailedError extends DecaneConnectError {
+    constructor(reason: string);
+}
+declare class InvalidRecoveryFileError extends DecaneConnectError {
+    constructor();
+}
+declare class WrongPasswordError extends DecaneConnectError {
+    constructor();
+}
+declare class RecoveryWalletMismatchError extends DecaneConnectError {
+    constructor();
+}
+declare class ExportNotAuthorizedError extends DecaneConnectError {
+    constructor();
+}
+
 declare class DecaneError extends Error {
     code: DecaneErrorCode;
     constructor(code: DecaneErrorCode, message: string);
@@ -217,16 +539,91 @@ interface WalletSelectorProps {
     onConnect: (wallet: UnifiedWalletAccount, preference?: ChainType) => void;
     theme?: "light" | "dark" | "auto";
     networks?: "evm" | "solana" | "tron" | "bitcoin" | "all";
+    mode?: ConnectMode;
+    socialAuthMethods?: ("google" | "email")[];
+    onGoogleSignIn?: () => Promise<void>;
+    onEmailStart?: (email: string) => Promise<{
+        codeRequired: true;
+    }>;
+    onEmailVerify?: (email: string, code: string) => Promise<void>;
 }
-declare function WalletSelector({ provider, open, onClose, onConnect, theme, networks, }: WalletSelectorProps): React.ReactPortal | null;
+declare function WalletSelector({ provider, open, onClose, onConnect, theme, networks, mode, socialAuthMethods, onGoogleSignIn, onEmailStart, onEmailVerify, }: WalletSelectorProps): React.ReactPortal | null;
 
 type Theme = "light" | "dark" | "auto";
+interface SocialAuthState {
+    addresses: {
+        evm?: string;
+        solana?: string;
+    } | null;
+    isNewUser: boolean;
+    isUnlocked: boolean;
+    sessionExpiresAt: number | null;
+}
 interface DecaneKitProps {
     config?: DecaneConfig;
     children: ReactNode;
 }
 declare function DecaneKit({ config, children }: DecaneKitProps): React.JSX.Element;
 
+interface SocialWalletModalProps {
+    open: boolean;
+    onClose: () => void;
+    theme?: "light" | "dark" | "auto";
+    socialAuth: SocialAuthState;
+    onUnlock: () => Promise<void>;
+    onDisconnect: () => Promise<void>;
+}
+declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, }: SocialWalletModalProps): React.ReactPortal | null;
+
+declare function useSocialAuth(): {
+    isConnected: boolean;
+    isUnlocked: boolean;
+    isNewUser: boolean;
+    addresses: {
+        evm?: string;
+        solana?: string;
+    } | null;
+    sessionExpiresAt: number | null;
+    googleLoading: boolean;
+    emailLoading: boolean;
+    error: string | null;
+    clearError: () => void;
+    signInWithGoogle: () => Promise<void>;
+    sendEmailCode: (email: string) => Promise<{
+        codeRequired: true;
+    }>;
+    confirmEmailCode: (email: string, code: string) => Promise<void>;
+    unlock: () => Promise<void>;
+    disconnect: () => Promise<void>;
+};
+declare function useSocialWallet(): {
+    isConnected: boolean;
+    isUnlocked: boolean;
+    isNewUser: boolean;
+    addresses: {
+        evm?: string;
+        solana?: string;
+    } | null;
+    sessionExpiresAt: number | null;
+    modalOpen: boolean;
+    openModal: () => void;
+    closeModal: () => void;
+    unlock: () => Promise<void>;
+    disconnect: () => Promise<void>;
+    signMessage: (chain: string, message: string | Uint8Array) => Promise<string>;
+    sendTransaction: (req: {
+        chain: string;
+        to: string;
+        value?: bigint;
+        data?: string;
+        gasLimit?: bigint;
+        gasPrice?: bigint;
+    }) => Promise<string>;
+    signSolanaTransaction: (tx: Uint8Array) => Promise<Uint8Array<ArrayBufferLike>>;
+    loading: boolean;
+    error: string | null;
+    clearError: () => void;
+};
 declare function useDecane(): {
     provider: DecaneProvider;
     wallets: UnifiedWalletAccount[];
@@ -299,4 +696,4 @@ declare function useSignTypedData(): {
     reset: () => void;
 };
 
-export { type ActiveSession, BUILT_IN_CHAINS, type CAIP25Method, type CAIP25SessionRequest, type CAIP25SessionResult, CHAINS, type ChainDescriptor, type ChainId, type ChainScope, type ChainSupport, type ChainType, type DecaneConfig, DecaneError, DecaneErrorCode, DecaneKit, type DecaneProvider, type Theme, type TxParams, type UnifiedWalletAccount, WalletSelector, createDecane, useChainSwitch, useDecane, useSendTransaction, useSignMessage, useSignTypedData, useWalletSelector };
+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 };