decane-connect-kit 2.7.5 → 2.7.6

package/dist/index.d.ts

@@ -1,476 +1,176 @@
 import * as _simplewebauthn_browser from '@simplewebauthn/browser';
 import React, { ReactNode } from 'react';
 
-type ChainType = "evm" | "solana" | "tron" | "bitcoin";
-type ChainSupport = ChainType[];
-interface ChainDescriptor {
-    id: string;
-    type: ChainType;
-    name: string;
-    nativeCurrency: {
-        name: string;
-        symbol: string;
-        decimals: number;
+interface RecoveryShareFile {
+    version: number;
+    type: 'decane-recovery-share';
+    shareSetVersion: number;
+    kdf: 'pbkdf2-sha256';
+    kdfParams: {
+        iterations: number;
+        salt: string;
     };
-    rpcUrl?: string;
-    blockExplorerUrl?: string;
-    iconUrl?: string;
-    chainId?: number;
-    isCustom?: boolean;
-}
-interface UnifiedWalletAccount {
-    id: string;
-    name: string;
-    icon: string;
-    rdns?: string;
-    chainSupport: ChainSupport;
-    evmProvider?: EIP1193Provider;
-    solanaProvider?: StandardWallet;
-    tronProvider?: TronProvider;
-    bitcoinProvider?: BitcoinProvider;
-}
-type CAIP25Method = "wallet_requestPermissions" | "wallet_revokePermissions" | "wallet_getPermissions" | "wallet_sendTransaction" | "wallet_signMessage" | "wallet_signTypedData";
-interface ChainScope {
-    methods: CAIP25Method[];
-    accounts: string[];
-    events?: string[];
-}
-interface CAIP25SessionRequest {
-    requiredScopes: Partial<Record<string, ChainScope>>;
-    optionalScopes: Partial<Record<string, ChainScope>>;
+    cipher: 'aes-256-gcm';
+    iv: string;
+    ciphertext: string;
+    addresses: {
+        evm: string;
+        solana: string;
+    };
+    passwordHint: string | null;
+    createdAt: string;
 }
-interface CAIP25SessionResult {
-    sessionId: string;
-    grantedScopes: Partial<Record<string, ChainScope>>;
+
+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;
 }
-interface ActiveSession {
-    sessionId: string;
-    grantedScopes: Partial<Record<string, ChainScope>>;
-    walletId: string;
-    walletType: ChainType | "multi";
-    createdAt: number;
+
+interface BalanceResult {
+    /** Smallest unit — wei for EVM, lamports for Solana. */
+    raw: bigint;
+    /** Human-readable amount in whole native units, e.g. "1.2345". */
+    formatted: string;
+    /** Native currency symbol, e.g. "ETH", "MATIC", "SOL". */
+    symbol: string;
+    /** Decimals of the native currency (18 for EVM, 9 for Solana). */
+    decimals: number;
 }
-interface DecaneProvider {
+
+interface Eip1193Provider {
     request(args: {
         method: string;
-        params?: unknown[];
+        params?: unknown[] | object;
     }): Promise<unknown>;
-    on(event: string, handler: (...args: unknown[]) => void): void;
-    off(event: string, handler: (...args: unknown[]) => void): void;
-    readonly wallets: UnifiedWalletAccount[];
-    readonly evmWallets: UnifiedWalletAccount[];
-    readonly solanaWallets: UnifiedWalletAccount[];
-    readonly multiChainWallets: UnifiedWalletAccount[];
-    readonly tronWallets: UnifiedWalletAccount[];
-    readonly bitcoinWallets: UnifiedWalletAccount[];
-    connect(wallet: UnifiedWalletAccount, preferredChain?: ChainType): Promise<void>;
-    disconnect(): Promise<void>;
-    addChain(chain: ChainDescriptor): void;
-    removeChain(chainId: string): void;
-    getChain(chainId: string): ChainDescriptor | undefined;
-    readonly chains: ChainDescriptor[];
-    readonly connectedWallet: UnifiedWalletAccount | null;
-    readonly activeSession: ActiveSession | null;
-    readonly activeChain: string | null;
+    on(event: string, handler: (...args: unknown[]) => void): this;
+    removeListener(event: string, handler: (...args: unknown[]) => void): this;
+    /** Marks this as the Decane provider (parallel to wallets' isMetaMask etc.). */
+    readonly isDecane: true;
 }
-type ConnectMode = "all" | "social" | "wallets" | "evm" | "solana" | "tron" | "evm+social" | "solana+social" | "tron+social" | "evm+tron" | "evm+tron+social";
-interface SocialConfig {
+interface EthereumProviderOptions {
+    /** Initial chain id (numeric). Defaults to the first configured EVM chain, else 1. */
+    chainId?: number;
+    /** Per-chain RPC overrides ('evm:8453' -> url). Falls back to Decane's defaults. */
+    rpcUrls?: Record<string, string>;
+}
+/**
+ * Build an EIP-1193 provider over a connected Decane social client.
+ *
+ * `signAuthorization` (EIP-7702) is wired only when the client exposes it — that
+ * requires the TEE signer to support the authorization signing path.
+ */
+declare function createEthereumProvider(client: DecaneConnect, opts?: EthereumProviderOptions): Eip1193Provider;
+
+interface SignedAuthorization {
+    chainId: number;
+    address: string;
+    nonce: number;
+    yParity: number;
+    r: string;
+    s: string;
+}
+
+type Chain = `evm:${number}` | `solana:${'mainnet' | 'devnet'}` | `tron:${'mainnet' | 'shasta' | 'nile'}`;
+interface DecaneConnectConfig {
+    /** Dashboard project ID (public). Sent with every request so the backend can
+     *  confirm the API key below actually belongs to this project. */
+    appId: string;
     apiKey: string;
-    authMethods?: ("google" | "email" | "kingschat")[];
+    chains: Chain[];
+    authMethods: Array<'google' | 'email' | 'kingschat'>;
     /**
-     * Scopes requested from KingsChat. Defaults to `['send_chat_message']`, which
-     * is what KingsChat's own SDK asks for and is enough to establish identity.
+     * Scopes requested from KingsChat at sign-in. Defaults to
+     * `['send_chat_message']`, which is what KingsChat's own SDK asks for and is
+     * enough to establish identity. Widen only if the app actually calls
+     * KingsChat APIs on the user's behalf — the consent screen lists every scope,
+     * so asking for more than you use costs conversions.
      */
     kingsChatScopes?: string[];
-    promptPin?: () => Promise<string>;
     apiBaseUrl?: string;
-    chains?: string[];
-    rpcUrls?: Record<string, string>;
+    sessionDurationMinutes?: number;
+    promptPin?: () => Promise<string>;
     /**
-     * Show the built-in full-screen status overlay while a wallet is being
-     * created or unlocked. Default **true**.
+     * Require a fresh WebAuthn assertion for every signature, instead of letting
+     * an unlocked session sign freely until it expires. The TEE session stays
+     * warm — this costs one authenticator prompt per signature, not a re-auth or
+     * re-attestation — and the check is enforced inside the enclave, not here.
      *
-     * The overlay exists because those flows can take several seconds and often
-     * run right after a Google redirect, when no modal of yours is mounted — so
-     * without it the page can look frozen. It is rendered by `<DecaneKit>` itself,
-     * as a portal, and injects its own theme tokens.
+     * Default false, which preserves the session-signing model: unlock once, sign
+     * for the session's lifetime with no further prompts.
      *
-     * Set false to suppress it and render your own. Everything it displays is
-     * already available to you: `useSocialAuth()` exposes `phase`
-     * (`"creating" | "unlocking" | null`) plus the `isCreatingWallet` /
-     * `isUnlockingWallet` booleans, and the client emits `wallet-creating` and
-     * `wallet-unlocking` events. If you suppress it, show something of your own —
-     * a silent multi-second pause reads as a broken page.
+     * Two things worth knowing before turning this on:
+     *  - Multi-step flows prompt per leg. An ERC-20 approve + swap is two
+     *    prompts, not one.
+     *  - The policy is declared by the client at session open, so it hardens a
+     *    leaked session handle (useless without the authenticator) but a fully
+     *    compromised page could open a session without it. Making it
+     *    unbypassable requires the policy to come from the server per user or
+     *    per project; that is not implemented yet.
      */
-    showStatusOverlay?: boolean;
+    requireAssertionPerSignature?: boolean;
+    rpId?: string;
+    rpName?: string;
+    rpcUrls?: Record<string, string>;
+    teeUrl?: string;
     /**
-     * Require a fresh WebAuthn assertion for every signature rather than letting
-     * an unlocked session sign freely until it expires. Enforced inside the TEE.
+     * Persist the live session (handle + JWT) in sessionStorage so a page RELOAD
+     * silently resumes it — no repeat passkey/sign-in. Survives reloads, cleared
+     * on tab close. Default true. Set false to require a fresh unlock on every
+     * page load (stricter, but the reload friction that motivated this returns).
+     */
+    persistSession?: boolean;
+    /**
+     * Offer to save a recovery-share file at signup. **Default false** since
+     * 2.7.4 — opt in explicitly with `true`.
      *
-     * Does not change the session lifetime — the session stays warm (no
-     * re-attestation, no re-auth) and authority is re-proven per signature
-     * instead. Default false. Needs a passkey; PIN-only wallets have no
-     * authenticator to assert with. See SocialConfig's counterpart in
-     * social/types.ts for the full caveats.
+     * The offer existed because a new device could not otherwise get a device
+     * share. Server-assisted provisioning now covers that case: every wallet is
+     * enrolled at creation, un-enrolled wallets repair themselves on the next
+     * unlock, and a returning user is provisioned from their sign-in alone. For
+     * almost every app the dialog is now a password prompt during onboarding that
+     * buys nothing, so it is off unless asked for.
+     *
+     * Recovery files themselves are unchanged and still work — `rotateShares()`
+     * issues one on demand, and `promptForRecoveryFile` still accepts one during
+     * recovery. Turn this back on if you want users to hold an offline fallback
+     * that does not depend on Decane being reachable.
      */
-    requireAssertionPerSignature?: boolean;
+    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>;
     /**
-     * Sign in with a token from your own auth system (Auth0, Clerk, Firebase,
-     * Cognito, or your own backend) — surfaced as a button in the built-in
-     * WalletSelector / SocialWalletModal UI, alongside Google and email.
-     * getToken() runs when the user clicks the button; wire it to however you
-     * already obtain a token from your auth system (e.g. after your own login
-     * flow completes). Configure the issuer and JWKS URL for this token
-     * against your project in the dashboard first. `providerId` is only
-     * needed when the project has more than one custom provider configured.
-     */
-    customAuth?: {
-        label: string;
-        providerId?: string;
-        getToken: () => Promise<string>;
-    };
-}
-interface DecaneConfig {
-    appId: string;
-    chains?: ChainDescriptor[];
-    supportedChainIds?: string[];
-    networks?: "evm" | "solana" | "tron" | "bitcoin" | "all";
-    defaultChain?: string;
-    theme?: "light" | "dark" | "auto";
-    mode?: ConnectMode;
-    social?: SocialConfig;
-}
-interface EIP1193Provider {
-    request(args: {
-        method: string;
-        params?: unknown[];
-    }): Promise<unknown>;
-    on(event: string, handler: (...args: unknown[]) => void): void;
-    removeListener(event: string, handler: (...args: unknown[]) => void): void;
-}
-interface StandardWallet {
-    name: string;
-    icon: string;
-    features: Record<string, unknown>;
-    accounts: StandardWalletAccount[];
-}
-interface StandardWalletAccount {
-    address: string;
-    publicKey: Uint8Array;
-    chains: string[];
-}
-interface TronProvider {
-    request(args: {
-        method: string;
-        params?: unknown[] | Record<string, unknown>;
-    }): Promise<unknown>;
-    on(event: string, handler: (...args: unknown[]) => void): void;
-    removeListener(event: string, handler: (...args: unknown[]) => void): void;
-}
-interface BitcoinProvider {
-    requestAccounts(): Promise<string[] | Array<{
-        address: string;
-    }>>;
-    getAccounts?(): Promise<string[] | Array<{
-        address: string;
-    }>>;
-    signMessage(message: string, ...args: unknown[]): Promise<string>;
-    sendBitcoin?(toAddress: string, satoshis: number, options?: unknown): Promise<string>;
-    send?(params: unknown): Promise<string>;
-    signPsbt?(psbtHex: string, options?: unknown): Promise<string>;
-    on?(event: string, handler: (...args: unknown[]) => void): void;
-}
-
-declare function createDecane(config: DecaneConfig): DecaneProvider;
-
-declare class ApiClient {
-    private readonly baseUrl;
-    private readonly apiKey;
-    private readonly appId;
-    constructor(baseUrl: string, apiKey: string, appId: string);
-    private _request;
-    getGoogleInitUrl(): Promise<{
-        url: string;
-    }>;
-    /**
-     * Exchange a Google ID token the app already holds for a Decane session.
-     * Resolves to the SAME identity as the redirect flow, so one Google account
-     * means one wallet across web and mobile.
-     */
-    authGoogleToken(idToken: string): Promise<AuthResult>;
-    /** The project's KingsChat clientId, so the dApp never has to hardcode it. */
-    getKingsChatConfig(): Promise<{
-        clientId: string;
-        authorizationUrl: string;
-    }>;
-    /**
-     * Exchange a KingsChat access token for a Decane session. The backend spends
-     * the token against KingsChat's own API to establish the identity — it is
-     * never trusted on its face, and never stored.
-     */
-    authKingsChat(accessToken: string): Promise<AuthResult>;
-    authEmailStart(email: string): Promise<void>;
-    authEmailVerify(email: string, code: string): Promise<AuthResult>;
-    getAddresses(jwt: string): Promise<{
-        evm: string | null;
-        solana: string | null;
-        tron: string | null;
-    }>;
-    putShare(jwt: string, share: {
-        ciphertext: Uint8Array;
-        iv: Uint8Array;
-        wrappedShareMeta: WrappedShareMeta;
-        evmAddress: string;
-        solanaAddress: string;
-        tronAddress: string;
-    }): Promise<void>;
-    recordTransaction(jwt: string, tx: {
-        chain: string;
-        txHash?: string;
-        to?: string;
-        value?: string;
-        kind?: string;
-        status?: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<TransactionRecord>;
-    getTransactions(jwt: string, limit?: number): Promise<TransactionRecord[]>;
-    getWebAuthnRegisterOptions(jwt: string, rpId: string, rpName: string): Promise<_simplewebauthn_browser.PublicKeyCredentialCreationOptionsJSON>;
-    postWebAuthnRegister(jwt: string, response: _simplewebauthn_browser.RegistrationResponseJSON, origin: string): Promise<void>;
-    /**
-     * Exchange a token from the developer's own auth system for a Decane
-     * session. `providerId` is only needed when the project has more than one
-     * provider configured.
-     */
-    authExternal(token: string, providerId?: string): Promise<AuthResult>;
-    /**
-     * Returns null when this user has no server-registered passkey, which is the
-     * expected answer for wallets created before passkey sign-in existed or for
-     * PIN-only users — the caller falls back to the normal sign-in flow.
-     */
-    getWebAuthnLoginOptions(userId: string, rpId: string): Promise<_simplewebauthn_browser.PublicKeyCredentialRequestOptionsJSON | null>;
-    postWebAuthnLogin(userId: string, response: _simplewebauthn_browser.AuthenticationResponseJSON, origin: string): Promise<AuthResult>;
-    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;
-        /**
-         * Whether this wallet is enrolled for server-assisted provisioning, i.e.
-         * whether a new device can be given a device share from login alone.
-         * Optional because backends older than this field simply omit it — treat
-         * `undefined` as "unknown", never as "not enrolled".
-         */
-        enrolled?: boolean;
-    }>;
-    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;
-}
-
-interface BalanceResult {
-    /** Smallest unit — wei for EVM, lamports for Solana. */
-    raw: bigint;
-    /** Human-readable amount in whole native units, e.g. "1.2345". */
-    formatted: string;
-    /** Native currency symbol, e.g. "ETH", "MATIC", "SOL". */
-    symbol: string;
-    /** Decimals of the native currency (18 for EVM, 9 for Solana). */
-    decimals: number;
-}
-
-interface Eip1193Provider {
-    request(args: {
-        method: string;
-        params?: unknown[] | object;
-    }): Promise<unknown>;
-    on(event: string, handler: (...args: unknown[]) => void): this;
-    removeListener(event: string, handler: (...args: unknown[]) => void): this;
-    /** Marks this as the Decane provider (parallel to wallets' isMetaMask etc.). */
-    readonly isDecane: true;
-}
-interface EthereumProviderOptions {
-    /** Initial chain id (numeric). Defaults to the first configured EVM chain, else 1. */
-    chainId?: number;
-    /** Per-chain RPC overrides ('evm:8453' -> url). Falls back to Decane's defaults. */
-    rpcUrls?: Record<string, string>;
-}
-/**
- * Build an EIP-1193 provider over a connected Decane social client.
- *
- * `signAuthorization` (EIP-7702) is wired only when the client exposes it — that
- * requires the TEE signer to support the authorization signing path.
- */
-declare function createEthereumProvider(client: DecaneConnect, opts?: EthereumProviderOptions): Eip1193Provider;
-
-interface SignedAuthorization {
-    chainId: number;
-    address: string;
-    nonce: number;
-    yParity: number;
-    r: string;
-    s: string;
-}
-
-type Chain = `evm:${number}` | `solana:${'mainnet' | 'devnet'}` | `tron:${'mainnet' | 'shasta' | 'nile'}`;
-interface DecaneConnectConfig {
-    /** Dashboard project ID (public). Sent with every request so the backend can
-     *  confirm the API key below actually belongs to this project. */
-    appId: string;
-    apiKey: string;
-    chains: Chain[];
-    authMethods: Array<'google' | 'email' | 'kingschat'>;
-    /**
-     * Scopes requested from KingsChat at sign-in. Defaults to
-     * `['send_chat_message']`, which is what KingsChat's own SDK asks for and is
-     * enough to establish identity. Widen only if the app actually calls
-     * KingsChat APIs on the user's behalf — the consent screen lists every scope,
-     * so asking for more than you use costs conversions.
-     */
-    kingsChatScopes?: string[];
-    apiBaseUrl?: string;
-    sessionDurationMinutes?: number;
-    promptPin?: () => Promise<string>;
-    /**
-     * Require a fresh WebAuthn assertion for every signature, instead of letting
-     * an unlocked session sign freely until it expires. The TEE session stays
-     * warm — this costs one authenticator prompt per signature, not a re-auth or
-     * re-attestation — and the check is enforced inside the enclave, not here.
-     *
-     * Default false, which preserves the session-signing model: unlock once, sign
-     * for the session's lifetime with no further prompts.
-     *
-     * Two things worth knowing before turning this on:
-     *  - Multi-step flows prompt per leg. An ERC-20 approve + swap is two
-     *    prompts, not one.
-     *  - The policy is declared by the client at session open, so it hardens a
-     *    leaked session handle (useless without the authenticator) but a fully
-     *    compromised page could open a session without it. Making it
-     *    unbypassable requires the policy to come from the server per user or
-     *    per project; that is not implemented yet.
-     */
-    requireAssertionPerSignature?: boolean;
-    rpId?: string;
-    rpName?: string;
-    rpcUrls?: Record<string, string>;
-    teeUrl?: string;
-    /**
-     * Persist the live session (handle + JWT) in sessionStorage so a page RELOAD
-     * silently resumes it — no repeat passkey/sign-in. Survives reloads, cleared
-     * on tab close. Default true. Set false to require a fresh unlock on every
-     * page load (stricter, but the reload friction that motivated this returns).
-     */
-    persistSession?: boolean;
-    /**
-     * Offer to save a recovery-share file at signup. **Default false** since
-     * 2.7.4 — opt in explicitly with `true`.
-     *
-     * The offer existed because a new device could not otherwise get a device
-     * share. Server-assisted provisioning now covers that case: every wallet is
-     * enrolled at creation, un-enrolled wallets repair themselves on the next
-     * unlock, and a returning user is provisioned from their sign-in alone. For
-     * almost every app the dialog is now a password prompt during onboarding that
-     * buys nothing, so it is off unless asked for.
-     *
-     * Recovery files themselves are unchanged and still work — `rotateShares()`
-     * issues one on demand, and `promptForRecoveryFile` still accepts one during
-     * recovery. Turn this back on if you want users to hold an offline fallback
-     * that does not depend on Decane being reachable.
-     */
-    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).
+     * 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;
@@ -669,112 +369,458 @@ interface DecaneConnect {
         nonce: number;
     }): Promise<SignedAuthorization>;
     /**
-     * The current session's access token (the Decane JWT). Use it to authenticate
-     * the user to your own backend (e.g. a sponsored-bundler proxy); verify it
-     * server-side against backend.decane.app/.well-known/jwks.json. Null with no
-     * live session.
+     * The current session's access token (the Decane JWT). Use it to authenticate
+     * the user to your own backend (e.g. a sponsored-bundler proxy); verify it
+     * server-side against backend.decane.app/.well-known/jwks.json. Null with no
+     * live session.
+     */
+    getAccessToken(): string | null;
+    signSolanaTransaction(tx: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Sign a Tron transaction. Pass the transaction's `raw_data_hex` (the value
+     * TronWeb puts on a built transaction). The enclave computes the txID
+     * (sha256(raw_data)) and signs it with the same secp256k1 key as the EVM
+     * wallet; returns the 65-byte recoverable signature as 0x-hex. Attach it to
+     * the transaction's `signature` array and broadcast via TronWeb / a full node.
+     */
+    signTronTransaction(rawDataHex: string): Promise<string>;
+    /**
+     * Record a transaction this wallet broadcast, so it appears in the user's
+     * history (and the developer dashboard). EVM `sendTransaction` records itself
+     * automatically; call this for Solana/Tron transactions your dApp broadcasts,
+     * or to attach a `confirmed`/`failed` status update to an existing hash.
+     */
+    recordTransaction(tx: RecordTransactionInput): Promise<TransactionRecord>;
+    /** The user's transaction history, most recent first. Requires a live session. */
+    getTransactionHistory(limit?: number): Promise<TransactionRecord[]>;
+    disconnect(): Promise<void>;
+    getAddresses(): {
+        evm?: string;
+        solana?: string;
+        tron?: string;
+    } | null;
+    /**
+     * Native-token balance for a chain (defaults to the first configured EVM
+     * chain, else Solana). Read-only public data — works even while the wallet
+     * is locked. Returns raw (wei/lamports), a human `formatted` string, the
+     * native `symbol`, and `decimals`.
+     */
+    getBalance(chain?: string): Promise<BalanceResult>;
+    /** Native balances across every configured chain the wallet has an address for. */
+    getBalances(): Promise<Array<{
+        chain: string;
+        balance: BalanceResult | 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;
+}
+/**
+ * Who the user is, as the identity provider just described them.
+ *
+ * Passed through from the provider at sign-in and never stored by Decane — the
+ * backend keeps only an HMAC and a masked identifier, so there is no profile to
+ * look up later. Cache what you need at sign-in if you want to show a name
+ * after a page reload.
+ *
+ * Every field is optional because providers differ in what they release, and a
+ * user can withhold most of it. Email sign-in returns an empty profile.
+ */
+interface AuthProfile {
+    name?: string;
+    email?: string;
+    picture?: string;
+}
+interface AuthResult {
+    jwt: string;
+    isNewUser: boolean;
+    hasShare: boolean;
+    userId: string;
+    profile?: AuthProfile;
+}
+
+declare class ApiClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly appId;
+    constructor(baseUrl: string, apiKey: string, appId: string);
+    private _request;
+    getGoogleInitUrl(): Promise<{
+        url: string;
+    }>;
+    /**
+     * Exchange a Google ID token the app already holds for a Decane session.
+     * Resolves to the SAME identity as the redirect flow, so one Google account
+     * means one wallet across web and mobile.
+     */
+    authGoogleToken(idToken: string): Promise<AuthResult>;
+    /** The project's KingsChat clientId, so the dApp never has to hardcode it. */
+    getKingsChatConfig(): Promise<{
+        clientId: string;
+        authorizationUrl: string;
+    }>;
+    /**
+     * Exchange a KingsChat access token for a Decane session. The backend spends
+     * the token against KingsChat's own API to establish the identity — it is
+     * never trusted on its face, and never stored.
+     */
+    authKingsChat(accessToken: string): Promise<AuthResult>;
+    authEmailStart(email: string): Promise<void>;
+    authEmailVerify(email: string, code: string): Promise<AuthResult>;
+    getAddresses(jwt: string): Promise<{
+        evm: string | null;
+        solana: string | null;
+        tron: string | null;
+    }>;
+    putShare(jwt: string, share: {
+        ciphertext: Uint8Array;
+        iv: Uint8Array;
+        wrappedShareMeta: WrappedShareMeta;
+        evmAddress: string;
+        solanaAddress: string;
+        tronAddress: string;
+    }): Promise<void>;
+    recordTransaction(jwt: string, tx: {
+        chain: string;
+        txHash?: string;
+        to?: string;
+        value?: string;
+        kind?: string;
+        status?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<TransactionRecord>;
+    getTransactions(jwt: string, limit?: number): Promise<TransactionRecord[]>;
+    getWebAuthnRegisterOptions(jwt: string, rpId: string, rpName: string): Promise<_simplewebauthn_browser.PublicKeyCredentialCreationOptionsJSON>;
+    postWebAuthnRegister(jwt: string, response: _simplewebauthn_browser.RegistrationResponseJSON, origin: string): Promise<void>;
+    /**
+     * Exchange a token from the developer's own auth system for a Decane
+     * session. `providerId` is only needed when the project has more than one
+     * provider configured.
+     */
+    authExternal(token: string, providerId?: string): Promise<AuthResult>;
+    /**
+     * Returns null when this user has no server-registered passkey, which is the
+     * expected answer for wallets created before passkey sign-in existed or for
+     * PIN-only users — the caller falls back to the normal sign-in flow.
+     */
+    getWebAuthnLoginOptions(userId: string, rpId: string): Promise<_simplewebauthn_browser.PublicKeyCredentialRequestOptionsJSON | null>;
+    postWebAuthnLogin(userId: string, response: _simplewebauthn_browser.AuthenticationResponseJSON, origin: string): Promise<AuthResult>;
+    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;
+        /**
+         * Whether this wallet is enrolled for server-assisted provisioning, i.e.
+         * whether a new device can be given a device share from login alone.
+         * Optional because backends older than this field simply omit it — treat
+         * `undefined` as "unknown", never as "not enrolled".
+         */
+        enrolled?: boolean;
+    }>;
+    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;
+};
+
+type ChainType = "evm" | "solana" | "tron" | "bitcoin";
+type ChainSupport = ChainType[];
+interface ChainDescriptor {
+    id: string;
+    type: ChainType;
+    name: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    rpcUrl?: string;
+    blockExplorerUrl?: string;
+    iconUrl?: string;
+    chainId?: number;
+    isCustom?: boolean;
+}
+interface UnifiedWalletAccount {
+    id: string;
+    name: string;
+    icon: string;
+    rdns?: string;
+    chainSupport: ChainSupport;
+    evmProvider?: EIP1193Provider;
+    solanaProvider?: StandardWallet;
+    tronProvider?: TronProvider;
+    bitcoinProvider?: BitcoinProvider;
+}
+type CAIP25Method = "wallet_requestPermissions" | "wallet_revokePermissions" | "wallet_getPermissions" | "wallet_sendTransaction" | "wallet_signMessage" | "wallet_signTypedData";
+interface ChainScope {
+    methods: CAIP25Method[];
+    accounts: string[];
+    events?: string[];
+}
+interface CAIP25SessionRequest {
+    requiredScopes: Partial<Record<string, ChainScope>>;
+    optionalScopes: Partial<Record<string, ChainScope>>;
+}
+interface CAIP25SessionResult {
+    sessionId: string;
+    grantedScopes: Partial<Record<string, ChainScope>>;
+}
+interface ActiveSession {
+    sessionId: string;
+    grantedScopes: Partial<Record<string, ChainScope>>;
+    walletId: string;
+    walletType: ChainType | "multi";
+    createdAt: number;
+}
+interface DecaneProvider {
+    request(args: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    readonly wallets: UnifiedWalletAccount[];
+    readonly evmWallets: UnifiedWalletAccount[];
+    readonly solanaWallets: UnifiedWalletAccount[];
+    readonly multiChainWallets: UnifiedWalletAccount[];
+    readonly tronWallets: UnifiedWalletAccount[];
+    readonly bitcoinWallets: UnifiedWalletAccount[];
+    connect(wallet: UnifiedWalletAccount, preferredChain?: ChainType): Promise<void>;
+    disconnect(): Promise<void>;
+    addChain(chain: ChainDescriptor): void;
+    removeChain(chainId: string): void;
+    getChain(chainId: string): ChainDescriptor | undefined;
+    readonly chains: ChainDescriptor[];
+    readonly connectedWallet: UnifiedWalletAccount | null;
+    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" | "kingschat")[];
+    /**
+     * Scopes requested from KingsChat. Defaults to `['send_chat_message']`, which
+     * is what KingsChat's own SDK asks for and is enough to establish identity.
      */
-    getAccessToken(): string | null;
-    signSolanaTransaction(tx: Uint8Array): Promise<Uint8Array>;
+    kingsChatScopes?: string[];
+    promptPin?: () => Promise<string>;
+    apiBaseUrl?: string;
+    chains?: string[];
+    rpcUrls?: Record<string, string>;
     /**
-     * Sign a Tron transaction. Pass the transaction's `raw_data_hex` (the value
-     * TronWeb puts on a built transaction). The enclave computes the txID
-     * (sha256(raw_data)) and signs it with the same secp256k1 key as the EVM
-     * wallet; returns the 65-byte recoverable signature as 0x-hex. Attach it to
-     * the transaction's `signature` array and broadcast via TronWeb / a full node.
+     * Show the built-in full-screen status overlay while a wallet is being
+     * created or unlocked. Default **true**.
+     *
+     * The overlay exists because those flows can take several seconds and often
+     * run right after a Google redirect, when no modal of yours is mounted — so
+     * without it the page can look frozen. It is rendered by `<DecaneKit>` itself,
+     * as a portal, and injects its own theme tokens.
+     *
+     * Set false to suppress it and render your own. Everything it displays is
+     * already available to you: `useSocialAuth()` exposes `phase`
+     * (`"creating" | "unlocking" | null`) plus the `isCreatingWallet` /
+     * `isUnlockingWallet` booleans, and the client emits `wallet-creating` and
+     * `wallet-unlocking` events. If you suppress it, show something of your own —
+     * a silent multi-second pause reads as a broken page.
      */
-    signTronTransaction(rawDataHex: string): Promise<string>;
+    showStatusOverlay?: boolean;
     /**
-     * Record a transaction this wallet broadcast, so it appears in the user's
-     * history (and the developer dashboard). EVM `sendTransaction` records itself
-     * automatically; call this for Solana/Tron transactions your dApp broadcasts,
-     * or to attach a `confirmed`/`failed` status update to an existing hash.
+     * Offer to save a recovery-share file at signup. **Default false** since
+     * 2.7.4 — opt in explicitly with `true`.
+     *
+     * Server-assisted provisioning now covers the new-device case (wallets are
+     * enrolled at creation and repair themselves on unlock), so for most apps
+     * this dialog is a password prompt during onboarding that buys nothing. Turn
+     * it on if you want users to hold an offline fallback that works when Decane
+     * is unreachable.
      */
-    recordTransaction(tx: RecordTransactionInput): Promise<TransactionRecord>;
-    /** The user's transaction history, most recent first. Requires a live session. */
-    getTransactionHistory(limit?: number): Promise<TransactionRecord[]>;
-    disconnect(): Promise<void>;
-    getAddresses(): {
-        evm?: string;
-        solana?: string;
-        tron?: string;
-    } | null;
+    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 app, which owns the download. */
+    onRecoveryFileReady?: (file: RecoveryShareFile, filename: string) => Promise<void>;
     /**
-     * Native-token balance for a chain (defaults to the first configured EVM
-     * chain, else Solana). Read-only public data — works even while the wallet
-     * is locked. Returns raw (wei/lamports), a human `formatted` string, the
-     * native `symbol`, and `decimals`.
+     * Prompt for a recovery-share file (and its password) during recovery.
+     * Return null to cancel. **Without this, a user who needs the recovery-file
+     * path fails immediately with NewDeviceError** — there is nowhere to ask them
+     * for the file.
      */
-    getBalance(chain?: string): Promise<BalanceResult>;
-    /** Native balances across every configured chain the wallet has an address for. */
-    getBalances(): Promise<Array<{
-        chain: string;
-        balance: BalanceResult | null;
-    }>>;
+    promptForRecoveryFile?: () => Promise<{
+        value: unknown;
+        getPassword: () => Promise<string | null>;
+    } | 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).
+     * Every successful recovery/rotation invalidates the previous recovery file,
+     * so this must prompt for a new password and capture the replacement.
+     * Required before recovery can run at all.
      */
-    rotateShares(opts: {
+    onRecoveryRotated?: (addresses: {
+        evmAddress: string;
+        solanaAddress: string;
+    }) => Promise<{
         password: string;
         passwordHint?: string;
-    }): Promise<RecoveryShareFile>;
+    }>;
+    /** Recovery stage callbacks, for your own progress UI. */
+    onRecoveryProgress?: (event: RecoveryProgress) => void;
     /**
-     * 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.
+     * Require a fresh WebAuthn assertion for every signature rather than letting
+     * an unlocked session sign freely until it expires. Enforced inside the TEE.
+     *
+     * Does not change the session lifetime — the session stays warm (no
+     * re-attestation, no re-auth) and authority is re-proven per signature
+     * instead. Default false. Needs a passkey; PIN-only wallets have no
+     * authenticator to assert with. See SocialConfig's counterpart in
+     * social/types.ts for the full caveats.
      */
-    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;
+    requireAssertionPerSignature?: boolean;
+    /**
+     * Sign in with a token from your own auth system (Auth0, Clerk, Firebase,
+     * Cognito, or your own backend) — surfaced as a button in the built-in
+     * WalletSelector / SocialWalletModal UI, alongside Google and email.
+     * getToken() runs when the user clicks the button; wire it to however you
+     * already obtain a token from your auth system (e.g. after your own login
+     * flow completes). Configure the issuer and JWKS URL for this token
+     * against your project in the dashboard first. `providerId` is only
+     * needed when the project has more than one custom provider configured.
+     */
+    customAuth?: {
+        label: string;
+        providerId?: string;
+        getToken: () => Promise<string>;
+    };
 }
-interface WrappedShareMeta {
-    unlockMethod: 'passkey' | 'pin';
-    credentialId?: string;
-    prfSalt?: string;
-    pinSalt?: string;
-    pinIterations?: number;
+interface DecaneConfig {
+    appId: string;
+    chains?: ChainDescriptor[];
+    supportedChainIds?: string[];
+    networks?: "evm" | "solana" | "tron" | "bitcoin" | "all";
+    defaultChain?: string;
+    theme?: "light" | "dark" | "auto";
+    mode?: ConnectMode;
+    social?: SocialConfig;
 }
-/**
- * Who the user is, as the identity provider just described them.
- *
- * Passed through from the provider at sign-in and never stored by Decane — the
- * backend keeps only an HMAC and a masked identifier, so there is no profile to
- * look up later. Cache what you need at sign-in if you want to show a name
- * after a page reload.
- *
- * Every field is optional because providers differ in what they release, and a
- * user can withhold most of it. Email sign-in returns an empty profile.
- */
-interface AuthProfile {
-    name?: string;
-    email?: string;
-    picture?: string;
+interface EIP1193Provider {
+    request(args: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    removeListener(event: string, handler: (...args: unknown[]) => void): void;
 }
-interface AuthResult {
-    jwt: string;
-    isNewUser: boolean;
-    hasShare: boolean;
-    userId: string;
-    profile?: AuthProfile;
+interface StandardWallet {
+    name: string;
+    icon: string;
+    features: Record<string, unknown>;
+    accounts: StandardWalletAccount[];
+}
+interface StandardWalletAccount {
+    address: string;
+    publicKey: Uint8Array;
+    chains: string[];
+}
+interface TronProvider {
+    request(args: {
+        method: string;
+        params?: unknown[] | Record<string, unknown>;
+    }): Promise<unknown>;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    removeListener(event: string, handler: (...args: unknown[]) => void): void;
+}
+interface BitcoinProvider {
+    requestAccounts(): Promise<string[] | Array<{
+        address: string;
+    }>>;
+    getAccounts?(): Promise<string[] | Array<{
+        address: string;
+    }>>;
+    signMessage(message: string, ...args: unknown[]): Promise<string>;
+    sendBitcoin?(toAddress: string, satoshis: number, options?: unknown): Promise<string>;
+    send?(params: unknown): Promise<string>;
+    signPsbt?(psbtHex: string, options?: unknown): Promise<string>;
+    on?(event: string, handler: (...args: unknown[]) => void): void;
 }
 
+declare function createDecane(config: DecaneConfig): DecaneProvider;
+
 declare function createDecaneConnect(config: DecaneConnectConfig): Promise<DecaneConnect>;
 
 /**