decane-connect-kit 2.0.3 → 2.2.0

package/dist/index.d.cts

@@ -81,8 +81,24 @@ interface SocialConfig {
     apiBaseUrl?: string;
     chains?: string[];
     rpcUrls?: Record<string, string>;
+    /**
+     * 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";
@@ -132,12 +148,13 @@ interface BitcoinProvider {
     on?(event: string, handler: (...args: unknown[]) => void): void;
 }
 
-declare function createDecane(config?: DecaneConfig): DecaneProvider;
+declare function createDecane(config: DecaneConfig): DecaneProvider;
 
 declare class ApiClient {
     private readonly baseUrl;
     private readonly apiKey;
-    constructor(baseUrl: string, apiKey: string);
+    private readonly appId;
+    constructor(baseUrl: string, apiKey: string, appId: string);
     private _request;
     getGoogleInitUrl(): Promise<{
         url: string;
@@ -157,6 +174,19 @@ declare class ApiClient {
     }): Promise<void>;
     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<{
@@ -244,12 +274,34 @@ interface PortableBackup {
 
 type Chain = `evm:${number}` | `solana:${'mainnet' | 'devnet'}`;
 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'>;
     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>;
@@ -313,6 +365,20 @@ interface DecaneConnect {
     connectWithEmail(email: string): Promise<{
         codeRequired: true;
     }>;
+    /**
+     * Sign in with a JWT from your own auth system (Auth0, Clerk, Firebase,
+     * Cognito, your own backend — anything that publishes a JWKS endpoint).
+     *
+     * Configure the issuer and JWKS URL against your project in the dashboard;
+     * no client-side setup and no secret in your dApp. `providerId` is only
+     * required if the project has more than one provider configured.
+     *
+     * The user's wallet is derived from the configured identity claim, so the
+     * same token subject always resolves to the same wallet.
+     */
+    connectWithToken(token: string, opts?: {
+        providerId?: string;
+    }): Promise<ConnectResult>;
     verifyEmailCode(email: string, code: string): Promise<ConnectResult>;
     unlock(): Promise<void>;
     isUnlocked(): boolean;
@@ -320,8 +386,25 @@ interface DecaneConnect {
      * 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.
+     *
+     * Note this can be true while canSignInWithPasskey() is also true — in which
+     * case "sign in again" costs one biometric prompt, not a full auth round
+     * trip. Prefer offering that over a Google/email button.
      */
     needsReconnect(): boolean;
+    /**
+     * True when a returning user can be signed straight back in with the passkey
+     * already on this device — no Google redirect, no email code. Requires a
+     * remembered identity plus a passkey-wrapped device share in local storage,
+     * so it is false on new devices and for PIN-only wallets.
+     */
+    canSignInWithPasskey(): Promise<boolean>;
+    /**
+     * Sign in using only the device passkey. connect() already tries this first
+     * when it's available, so call this directly only when driving the UI
+     * yourself. Throws NewDeviceError when this device isn't eligible.
+     */
+    signInWithPasskey(): Promise<ConnectResult>;
     sessionExpiresAt(): number | null;
     signMessage(req: SignMessageRequest): Promise<string>;
     sendTransaction(req: SendTransactionRequest): Promise<string>;
@@ -568,8 +651,16 @@ interface WalletSelectorProps {
         codeRequired: true;
     }>;
     onEmailVerify?: (email: string, code: string) => Promise<void>;
-}
-declare function WalletSelector({ provider, open, onClose, onConnect, theme, networks, mode, socialAuthMethods, onGoogleSignIn, onEmailStart, onEmailVerify, }: WalletSelectorProps): React.ReactPortal | null;
+    /** Button text for the developer's own auth system, e.g. "Continue with Acme Inc". Omitted entirely when not configured. */
+    customAuthLabel?: string;
+    onCustomAuthSignIn?: () => Promise<void>;
+    /** Returning user on this device — offer the passkey instead of sign-in. */
+    canUsePasskey?: boolean;
+    /** Address shown alongside the passkey button, so they know who they're resuming as. */
+    passkeyAddress?: string | null;
+    onPasskeySignIn?: () => Promise<unknown>;
+}
+declare function WalletSelector({ provider, open, onClose, onConnect, theme, networks, mode, socialAuthMethods, onGoogleSignIn, onEmailStart, onEmailVerify, customAuthLabel, onCustomAuthSignIn, canUsePasskey, passkeyAddress, onPasskeySignIn, }: WalletSelectorProps): React.ReactPortal | null;
 
 type Theme = "light" | "dark" | "auto";
 interface SocialAuthState {
@@ -586,10 +677,16 @@ interface SocialAuthState {
      * 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.
+     * should route this into a full reconnect — but see canUsePasskey: when
+     * that is true the reconnect is a single biometric prompt rather than a
+     * Google redirect or an email code.
      */
     needsReconnect: boolean;
+    /**
+     * True when this device holds a passkey-wrapped share for the remembered
+     * user, so signing back in costs one passkey prompt and nothing else.
+     */
+    canUsePasskey: boolean;
 }
 interface DecaneKitProps {
     config?: DecaneConfig;
@@ -610,6 +707,8 @@ interface SocialWalletModalProps {
     }>;
     onEmailVerify: (email: string, code: string) => Promise<void>;
     authMethods?: Array<"google" | "email">;
+    customAuthLabel?: string;
+    onCustomAuthSignIn?: () => Promise<void>;
     onRotateShares: (opts: {
         password: string;
         passwordHint?: string;
@@ -621,7 +720,7 @@ interface SocialWalletModalProps {
     rpcUrls?: Record<string, string>;
     chains?: string[];
 }
-declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, onGoogleSignIn, onEmailStart, onEmailVerify, authMethods, onRotateShares, onExportPortableBackup, rpcUrls, chains, }: SocialWalletModalProps): React.ReactPortal | null;
+declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, onGoogleSignIn, onEmailStart, onEmailVerify, authMethods, customAuthLabel, onCustomAuthSignIn, onRotateShares, onExportPortableBackup, rpcUrls, chains, }: SocialWalletModalProps): React.ReactPortal | null;
 
 declare function useSocialAuth(): {
     isConnected: boolean;
@@ -635,6 +734,9 @@ declare function useSocialAuth(): {
     needsReconnect: boolean;
     googleLoading: boolean;
     emailLoading: boolean;
+    tokenLoading: boolean;
+    customLoading: boolean;
+    customAuthLabel: string | undefined;
     error: string | null;
     clearError: () => void;
     signInWithGoogle: () => Promise<void>;
@@ -642,6 +744,10 @@ declare function useSocialAuth(): {
         codeRequired: true;
     }>;
     confirmEmailCode: (email: string, code: string) => Promise<void>;
+    signInWithToken: (token: string, opts?: {
+        providerId?: string;
+    }) => Promise<void>;
+    signInWithCustomAuth: (() => Promise<void>) | undefined;
     unlock: () => Promise<void>;
     disconnect: () => Promise<void>;
 };

package/dist/index.d.ts

@@ -81,8 +81,24 @@ interface SocialConfig {
     apiBaseUrl?: string;
     chains?: string[];
     rpcUrls?: Record<string, string>;
+    /**
+     * 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";
@@ -132,12 +148,13 @@ interface BitcoinProvider {
     on?(event: string, handler: (...args: unknown[]) => void): void;
 }
 
-declare function createDecane(config?: DecaneConfig): DecaneProvider;
+declare function createDecane(config: DecaneConfig): DecaneProvider;
 
 declare class ApiClient {
     private readonly baseUrl;
     private readonly apiKey;
-    constructor(baseUrl: string, apiKey: string);
+    private readonly appId;
+    constructor(baseUrl: string, apiKey: string, appId: string);
     private _request;
     getGoogleInitUrl(): Promise<{
         url: string;
@@ -157,6 +174,19 @@ declare class ApiClient {
     }): Promise<void>;
     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<{
@@ -244,12 +274,34 @@ interface PortableBackup {
 
 type Chain = `evm:${number}` | `solana:${'mainnet' | 'devnet'}`;
 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'>;
     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>;
@@ -313,6 +365,20 @@ interface DecaneConnect {
     connectWithEmail(email: string): Promise<{
         codeRequired: true;
     }>;
+    /**
+     * Sign in with a JWT from your own auth system (Auth0, Clerk, Firebase,
+     * Cognito, your own backend — anything that publishes a JWKS endpoint).
+     *
+     * Configure the issuer and JWKS URL against your project in the dashboard;
+     * no client-side setup and no secret in your dApp. `providerId` is only
+     * required if the project has more than one provider configured.
+     *
+     * The user's wallet is derived from the configured identity claim, so the
+     * same token subject always resolves to the same wallet.
+     */
+    connectWithToken(token: string, opts?: {
+        providerId?: string;
+    }): Promise<ConnectResult>;
     verifyEmailCode(email: string, code: string): Promise<ConnectResult>;
     unlock(): Promise<void>;
     isUnlocked(): boolean;
@@ -320,8 +386,25 @@ interface DecaneConnect {
      * 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.
+     *
+     * Note this can be true while canSignInWithPasskey() is also true — in which
+     * case "sign in again" costs one biometric prompt, not a full auth round
+     * trip. Prefer offering that over a Google/email button.
      */
     needsReconnect(): boolean;
+    /**
+     * True when a returning user can be signed straight back in with the passkey
+     * already on this device — no Google redirect, no email code. Requires a
+     * remembered identity plus a passkey-wrapped device share in local storage,
+     * so it is false on new devices and for PIN-only wallets.
+     */
+    canSignInWithPasskey(): Promise<boolean>;
+    /**
+     * Sign in using only the device passkey. connect() already tries this first
+     * when it's available, so call this directly only when driving the UI
+     * yourself. Throws NewDeviceError when this device isn't eligible.
+     */
+    signInWithPasskey(): Promise<ConnectResult>;
     sessionExpiresAt(): number | null;
     signMessage(req: SignMessageRequest): Promise<string>;
     sendTransaction(req: SendTransactionRequest): Promise<string>;
@@ -568,8 +651,16 @@ interface WalletSelectorProps {
         codeRequired: true;
     }>;
     onEmailVerify?: (email: string, code: string) => Promise<void>;
-}
-declare function WalletSelector({ provider, open, onClose, onConnect, theme, networks, mode, socialAuthMethods, onGoogleSignIn, onEmailStart, onEmailVerify, }: WalletSelectorProps): React.ReactPortal | null;
+    /** Button text for the developer's own auth system, e.g. "Continue with Acme Inc". Omitted entirely when not configured. */
+    customAuthLabel?: string;
+    onCustomAuthSignIn?: () => Promise<void>;
+    /** Returning user on this device — offer the passkey instead of sign-in. */
+    canUsePasskey?: boolean;
+    /** Address shown alongside the passkey button, so they know who they're resuming as. */
+    passkeyAddress?: string | null;
+    onPasskeySignIn?: () => Promise<unknown>;
+}
+declare function WalletSelector({ provider, open, onClose, onConnect, theme, networks, mode, socialAuthMethods, onGoogleSignIn, onEmailStart, onEmailVerify, customAuthLabel, onCustomAuthSignIn, canUsePasskey, passkeyAddress, onPasskeySignIn, }: WalletSelectorProps): React.ReactPortal | null;
 
 type Theme = "light" | "dark" | "auto";
 interface SocialAuthState {
@@ -586,10 +677,16 @@ interface SocialAuthState {
      * 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.
+     * should route this into a full reconnect — but see canUsePasskey: when
+     * that is true the reconnect is a single biometric prompt rather than a
+     * Google redirect or an email code.
      */
     needsReconnect: boolean;
+    /**
+     * True when this device holds a passkey-wrapped share for the remembered
+     * user, so signing back in costs one passkey prompt and nothing else.
+     */
+    canUsePasskey: boolean;
 }
 interface DecaneKitProps {
     config?: DecaneConfig;
@@ -610,6 +707,8 @@ interface SocialWalletModalProps {
     }>;
     onEmailVerify: (email: string, code: string) => Promise<void>;
     authMethods?: Array<"google" | "email">;
+    customAuthLabel?: string;
+    onCustomAuthSignIn?: () => Promise<void>;
     onRotateShares: (opts: {
         password: string;
         passwordHint?: string;
@@ -621,7 +720,7 @@ interface SocialWalletModalProps {
     rpcUrls?: Record<string, string>;
     chains?: string[];
 }
-declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, onGoogleSignIn, onEmailStart, onEmailVerify, authMethods, onRotateShares, onExportPortableBackup, rpcUrls, chains, }: SocialWalletModalProps): React.ReactPortal | null;
+declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, onGoogleSignIn, onEmailStart, onEmailVerify, authMethods, customAuthLabel, onCustomAuthSignIn, onRotateShares, onExportPortableBackup, rpcUrls, chains, }: SocialWalletModalProps): React.ReactPortal | null;
 
 declare function useSocialAuth(): {
     isConnected: boolean;
@@ -635,6 +734,9 @@ declare function useSocialAuth(): {
     needsReconnect: boolean;
     googleLoading: boolean;
     emailLoading: boolean;
+    tokenLoading: boolean;
+    customLoading: boolean;
+    customAuthLabel: string | undefined;
     error: string | null;
     clearError: () => void;
     signInWithGoogle: () => Promise<void>;
@@ -642,6 +744,10 @@ declare function useSocialAuth(): {
         codeRequired: true;
     }>;
     confirmEmailCode: (email: string, code: string) => Promise<void>;
+    signInWithToken: (token: string, opts?: {
+        providerId?: string;
+    }) => Promise<void>;
+    signInWithCustomAuth: (() => Promise<void>) | undefined;
     unlock: () => Promise<void>;
     disconnect: () => Promise<void>;
 };