@lumiapassport/ui-kit 1.14.26 → 1.15.1

package/dist/index.d.cts

@@ -985,6 +985,55 @@ interface UseLogoutReturn {
  */
 declare function useLogout(): UseLogoutReturn;
 
+/**
+ * Nickname fingerprint verification utilities
+ * Implements client-side verification per FRD spec
+ *
+ * IMPORTANT: Client MUST NOT trust server blindly.
+ * Always verify fingerprint locally before displaying to user.
+ */
+/**
+ * Generate fingerprint from owner address
+ * Must match backend algorithm exactly
+ *
+ * Algorithm:
+ * 1. Normalize address to checksum format
+ * 2. Compute keccak256 hash
+ * 3. Take first 5 bytes (40 bits)
+ * 4. Encode using Base32 alphabet
+ * 5. Format as XXXX-XXXX
+ *
+ * @param ownerAddress - The EOA owner address
+ * @returns Fingerprint in format "XXXX-XXXX"
+ */
+declare function generateFingerprint(ownerAddress: string): string;
+/**
+ * Verify that received fingerprint matches computed fingerprint
+ *
+ * @param ownerAddress - The owner address from API response
+ * @param receivedFingerprint - The fingerprint from API response
+ * @returns true if fingerprint is valid, false if verification failed
+ */
+declare function verifyFingerprint(ownerAddress: string, receivedFingerprint: string): boolean;
+/**
+ * Fingerprint verification result
+ */
+interface FingerprintVerificationResult {
+    isValid: boolean;
+    computedFingerprint: string | null;
+    receivedFingerprint: string | null;
+    error?: string;
+}
+/**
+ * Verify fingerprint with detailed result
+ * Use this for UI display of verification status
+ *
+ * @param ownerAddress - The owner address from API response
+ * @param receivedFingerprint - The fingerprint from API response
+ * @returns Detailed verification result
+ */
+declare function verifyFingerprintDetailed(ownerAddress: string | null, receivedFingerprint: string | null): FingerprintVerificationResult;
+
 /**
  * Nickname API types
  * Types for nickname-related API responses and requests
@@ -1023,14 +1072,40 @@ interface NicknameAvailability {
 }
 type NicknameUnavailableReason = 'TAKEN' | 'RESERVED' | 'TOO_SHORT' | 'TOO_LONG' | 'INVALID_CHARS' | 'INVALID_UNDERSCORE';
 /**
- * Nickname to wallet address resolution
- * Returned by GET /api/auth/nicknames/{handle}/resolve
+ * Resolved target for a specific chain
+ */
+interface NicknameResolvedTarget {
+    chainId: number;
+    wallet: `0x${string}`;
+}
+/**
+ * Avatar information for nickname resolution
+ */
+interface NicknameAvatar {
+    type: 'deterministic-circles';
+    seed: string;
+}
+/**
+ * Nickname to wallet address resolution (v2)
+ * Returned by POST /api/auth/nicknames/resolve
  */
 interface NicknameResolution {
     handle: string;
-    displayHandle: string;
-    walletAddress: `0x${string}`;
-    ownerAddress: `0x${string}`;
+    requestedChainId: number;
+    resolvedTarget: NicknameResolvedTarget | null;
+    availableTargets: NicknameResolvedTarget[];
+    owner: `0x${string}` | null;
+    fingerprint: string | null;
+    avatar: NicknameAvatar | null;
+    avatarSvg: string | null;
+    isFrozen: boolean;
+}
+/**
+ * Request body for resolving nickname (v2)
+ */
+interface NicknameResolveRequest {
+    handle: string;
+    chainId: number;
 }
 /**
  * Client-side nickname validation result
@@ -1043,7 +1118,7 @@ type NicknameValidationError = 'TOO_SHORT' | 'TOO_LONG' | 'INVALID_CHARS' | 'INV
 
 /**
  * useNicknameResolve hook
- * Public hook for resolving nicknames to wallet addresses
+ * Public hook for resolving nicknames to wallet addresses with verification
  */
 
 interface UseNicknameResolveResult {
@@ -1052,6 +1127,10 @@ interface UseNicknameResolveResult {
     isResolving: boolean;
     isError: boolean;
     isNotFound: boolean;
+    isWalletNotSetup: boolean;
+    isFrozen: boolean;
+    isFingerprintVerified: boolean;
+    fingerprintVerification: FingerprintVerificationResult | null;
     error: Error | null;
     resolvedAddress: string | null;
 }
@@ -1061,18 +1140,23 @@ interface UseNicknameResolveResult {
  * - Does not start with 0x
  */
 declare function looksLikeNickname(input: string): boolean;
+interface UseNicknameResolveOptions {
+    enabled?: boolean;
+    chainId: number;
+}
 /**
- * Hook to resolve a nickname to a wallet address
+ * Hook to resolve a nickname to a wallet address with verification
  *
  * - Debounces API calls by 300ms
  * - Only resolves when input looks like a nickname
- * - Returns resolved address when found
+ * - Verifies fingerprint locally before returning data (MANDATORY)
+ * - Returns resolved address when found and verified
  *
  * @param input - The recipient input (can be address or nickname)
- * @param enabled - Whether resolution should be enabled (default: true)
- * @returns Resolution data, loading states, error state, resolved address
+ * @param options - Resolution options including chainId (required) and enabled flag
+ * @returns Resolution data, loading states, error state, verification status, resolved address
  */
-declare function useNicknameResolve(input: string, enabled?: boolean): UseNicknameResolveResult;
+declare function useNicknameResolve(input: string, options: UseNicknameResolveOptions): UseNicknameResolveResult;
 
 declare const LUMIA_EXPLORER_URL: string;
 declare const lumiaBeam: Chain;
@@ -1496,4 +1580,4 @@ declare function useLumiaPassportLinkedProfiles(): {
     refresh: () => Promise<void>;
 };
 
-export { type AccountSession, Address, type AddressProps, type Asset, ConnectWalletButton, type ConnectWalletButtonProps, ErrorCodes, Hash, type HashProps, KeyshareBackupMenu as KeyshareBackup, LUMIA_EXPLORER_URL, LumiaLogo, type LumiaPassportCallbacks, type LumiaPassportConfig, LumiaPassportError, LumiaPassportProvider, type LumiaPassportProviderProps, LumiaPassportSessionProvider, LumiaRainbowKitProvider, LumiaWagmiProvider, type NicknameAvailability, type NicknameChangeResult, type NicknameInfo, type NicknameResolution, type NicknameValidationResult, PageKey, type PageOpenParams, type ProviderDetail, type SendTransactionParams, type SendTransactionResult, type SignTypedDataParams, ThemeToggle, type TokenBalance, type Transaction, TransactionsList, type TypedDataDomain, type TypedDataField, type UpdateProfileRequest, type UseLogoutReturn, type UseNicknameResolveResult, type UseSendTransactionReturn, type UseUserOpStatusOptions, type UseUserOpStatusReturn, type UserOpMempool, type UserOpReceipt, type SendTransactionParams$1 as UserOpSendTransactionParams, type UserOpState, UserOpStatus, type UserOpStatusProps, type UserOperation, type UserProfile, UserRejectedError, type WalletReadyStatus, createLumiaPassportError, deployAccount, destroyIframeManager, getIframeManager, getUserProfile, looksLikeNickname, lumiaBeam, prepareUserOperation, queryClient, sendUserOperation, signTypedData, updateUserProfile, useAssets, useLogout, useLumiaPassportAccountSession, useLumiaPassportAddress, useLumiaPassportBalance, useLumiaPassportColorMode, useLumiaPassportConfig, useLumiaPassportError, useLumiaPassportHasServerVault, useLumiaPassportIFrameReady, useLumiaPassportIsMobileView, useLumiaPassportLinkedProfiles, useLumiaPassportLoadingStatus, useLumiaPassportOpen, useLumiaPassportRecoveryUserId, useLumiaPassportSession, useNicknameResolve, useSendTransaction, useSmartAccountTransactions, useTokenBalance, useTokenInfo, useTransactions, useUserOpStatus, wagmiConfig };
+export { type AccountSession, Address, type AddressProps, type Asset, ConnectWalletButton, type ConnectWalletButtonProps, ErrorCodes, type FingerprintVerificationResult, Hash, type HashProps, KeyshareBackupMenu as KeyshareBackup, LUMIA_EXPLORER_URL, LumiaLogo, type LumiaPassportCallbacks, type LumiaPassportConfig, LumiaPassportError, LumiaPassportProvider, type LumiaPassportProviderProps, LumiaPassportSessionProvider, LumiaRainbowKitProvider, LumiaWagmiProvider, type NicknameAvailability, type NicknameAvatar, type NicknameChangeResult, type NicknameInfo, type NicknameResolution, type NicknameResolveRequest, type NicknameResolvedTarget, type NicknameValidationResult, PageKey, type PageOpenParams, type ProviderDetail, type SendTransactionParams, type SendTransactionResult, type SignTypedDataParams, ThemeToggle, type TokenBalance, type Transaction, TransactionsList, type TypedDataDomain, type TypedDataField, type UpdateProfileRequest, type UseLogoutReturn, type UseNicknameResolveOptions, type UseNicknameResolveResult, type UseSendTransactionReturn, type UseUserOpStatusOptions, type UseUserOpStatusReturn, type UserOpMempool, type UserOpReceipt, type SendTransactionParams$1 as UserOpSendTransactionParams, type UserOpState, UserOpStatus, type UserOpStatusProps, type UserOperation, type UserProfile, UserRejectedError, type WalletReadyStatus, createLumiaPassportError, deployAccount, destroyIframeManager, generateFingerprint, getIframeManager, getUserProfile, looksLikeNickname, lumiaBeam, prepareUserOperation, queryClient, sendUserOperation, signTypedData, updateUserProfile, useAssets, useLogout, useLumiaPassportAccountSession, useLumiaPassportAddress, useLumiaPassportBalance, useLumiaPassportColorMode, useLumiaPassportConfig, useLumiaPassportError, useLumiaPassportHasServerVault, useLumiaPassportIFrameReady, useLumiaPassportIsMobileView, useLumiaPassportLinkedProfiles, useLumiaPassportLoadingStatus, useLumiaPassportOpen, useLumiaPassportRecoveryUserId, useLumiaPassportSession, useNicknameResolve, useSendTransaction, useSmartAccountTransactions, useTokenBalance, useTokenInfo, useTransactions, useUserOpStatus, verifyFingerprint, verifyFingerprintDetailed, wagmiConfig };

package/dist/index.d.ts

@@ -985,6 +985,55 @@ interface UseLogoutReturn {
  */
 declare function useLogout(): UseLogoutReturn;
 
+/**
+ * Nickname fingerprint verification utilities
+ * Implements client-side verification per FRD spec
+ *
+ * IMPORTANT: Client MUST NOT trust server blindly.
+ * Always verify fingerprint locally before displaying to user.
+ */
+/**
+ * Generate fingerprint from owner address
+ * Must match backend algorithm exactly
+ *
+ * Algorithm:
+ * 1. Normalize address to checksum format
+ * 2. Compute keccak256 hash
+ * 3. Take first 5 bytes (40 bits)
+ * 4. Encode using Base32 alphabet
+ * 5. Format as XXXX-XXXX
+ *
+ * @param ownerAddress - The EOA owner address
+ * @returns Fingerprint in format "XXXX-XXXX"
+ */
+declare function generateFingerprint(ownerAddress: string): string;
+/**
+ * Verify that received fingerprint matches computed fingerprint
+ *
+ * @param ownerAddress - The owner address from API response
+ * @param receivedFingerprint - The fingerprint from API response
+ * @returns true if fingerprint is valid, false if verification failed
+ */
+declare function verifyFingerprint(ownerAddress: string, receivedFingerprint: string): boolean;
+/**
+ * Fingerprint verification result
+ */
+interface FingerprintVerificationResult {
+    isValid: boolean;
+    computedFingerprint: string | null;
+    receivedFingerprint: string | null;
+    error?: string;
+}
+/**
+ * Verify fingerprint with detailed result
+ * Use this for UI display of verification status
+ *
+ * @param ownerAddress - The owner address from API response
+ * @param receivedFingerprint - The fingerprint from API response
+ * @returns Detailed verification result
+ */
+declare function verifyFingerprintDetailed(ownerAddress: string | null, receivedFingerprint: string | null): FingerprintVerificationResult;
+
 /**
  * Nickname API types
  * Types for nickname-related API responses and requests
@@ -1023,14 +1072,40 @@ interface NicknameAvailability {
 }
 type NicknameUnavailableReason = 'TAKEN' | 'RESERVED' | 'TOO_SHORT' | 'TOO_LONG' | 'INVALID_CHARS' | 'INVALID_UNDERSCORE';
 /**
- * Nickname to wallet address resolution
- * Returned by GET /api/auth/nicknames/{handle}/resolve
+ * Resolved target for a specific chain
+ */
+interface NicknameResolvedTarget {
+    chainId: number;
+    wallet: `0x${string}`;
+}
+/**
+ * Avatar information for nickname resolution
+ */
+interface NicknameAvatar {
+    type: 'deterministic-circles';
+    seed: string;
+}
+/**
+ * Nickname to wallet address resolution (v2)
+ * Returned by POST /api/auth/nicknames/resolve
  */
 interface NicknameResolution {
     handle: string;
-    displayHandle: string;
-    walletAddress: `0x${string}`;
-    ownerAddress: `0x${string}`;
+    requestedChainId: number;
+    resolvedTarget: NicknameResolvedTarget | null;
+    availableTargets: NicknameResolvedTarget[];
+    owner: `0x${string}` | null;
+    fingerprint: string | null;
+    avatar: NicknameAvatar | null;
+    avatarSvg: string | null;
+    isFrozen: boolean;
+}
+/**
+ * Request body for resolving nickname (v2)
+ */
+interface NicknameResolveRequest {
+    handle: string;
+    chainId: number;
 }
 /**
  * Client-side nickname validation result
@@ -1043,7 +1118,7 @@ type NicknameValidationError = 'TOO_SHORT' | 'TOO_LONG' | 'INVALID_CHARS' | 'INV
 
 /**
  * useNicknameResolve hook
- * Public hook for resolving nicknames to wallet addresses
+ * Public hook for resolving nicknames to wallet addresses with verification
  */
 
 interface UseNicknameResolveResult {
@@ -1052,6 +1127,10 @@ interface UseNicknameResolveResult {
     isResolving: boolean;
     isError: boolean;
     isNotFound: boolean;
+    isWalletNotSetup: boolean;
+    isFrozen: boolean;
+    isFingerprintVerified: boolean;
+    fingerprintVerification: FingerprintVerificationResult | null;
     error: Error | null;
     resolvedAddress: string | null;
 }
@@ -1061,18 +1140,23 @@ interface UseNicknameResolveResult {
  * - Does not start with 0x
  */
 declare function looksLikeNickname(input: string): boolean;
+interface UseNicknameResolveOptions {
+    enabled?: boolean;
+    chainId: number;
+}
 /**
- * Hook to resolve a nickname to a wallet address
+ * Hook to resolve a nickname to a wallet address with verification
  *
  * - Debounces API calls by 300ms
  * - Only resolves when input looks like a nickname
- * - Returns resolved address when found
+ * - Verifies fingerprint locally before returning data (MANDATORY)
+ * - Returns resolved address when found and verified
  *
  * @param input - The recipient input (can be address or nickname)
- * @param enabled - Whether resolution should be enabled (default: true)
- * @returns Resolution data, loading states, error state, resolved address
+ * @param options - Resolution options including chainId (required) and enabled flag
+ * @returns Resolution data, loading states, error state, verification status, resolved address
  */
-declare function useNicknameResolve(input: string, enabled?: boolean): UseNicknameResolveResult;
+declare function useNicknameResolve(input: string, options: UseNicknameResolveOptions): UseNicknameResolveResult;
 
 declare const LUMIA_EXPLORER_URL: string;
 declare const lumiaBeam: Chain;
@@ -1496,4 +1580,4 @@ declare function useLumiaPassportLinkedProfiles(): {
     refresh: () => Promise<void>;
 };
 
-export { type AccountSession, Address, type AddressProps, type Asset, ConnectWalletButton, type ConnectWalletButtonProps, ErrorCodes, Hash, type HashProps, KeyshareBackupMenu as KeyshareBackup, LUMIA_EXPLORER_URL, LumiaLogo, type LumiaPassportCallbacks, type LumiaPassportConfig, LumiaPassportError, LumiaPassportProvider, type LumiaPassportProviderProps, LumiaPassportSessionProvider, LumiaRainbowKitProvider, LumiaWagmiProvider, type NicknameAvailability, type NicknameChangeResult, type NicknameInfo, type NicknameResolution, type NicknameValidationResult, PageKey, type PageOpenParams, type ProviderDetail, type SendTransactionParams, type SendTransactionResult, type SignTypedDataParams, ThemeToggle, type TokenBalance, type Transaction, TransactionsList, type TypedDataDomain, type TypedDataField, type UpdateProfileRequest, type UseLogoutReturn, type UseNicknameResolveResult, type UseSendTransactionReturn, type UseUserOpStatusOptions, type UseUserOpStatusReturn, type UserOpMempool, type UserOpReceipt, type SendTransactionParams$1 as UserOpSendTransactionParams, type UserOpState, UserOpStatus, type UserOpStatusProps, type UserOperation, type UserProfile, UserRejectedError, type WalletReadyStatus, createLumiaPassportError, deployAccount, destroyIframeManager, getIframeManager, getUserProfile, looksLikeNickname, lumiaBeam, prepareUserOperation, queryClient, sendUserOperation, signTypedData, updateUserProfile, useAssets, useLogout, useLumiaPassportAccountSession, useLumiaPassportAddress, useLumiaPassportBalance, useLumiaPassportColorMode, useLumiaPassportConfig, useLumiaPassportError, useLumiaPassportHasServerVault, useLumiaPassportIFrameReady, useLumiaPassportIsMobileView, useLumiaPassportLinkedProfiles, useLumiaPassportLoadingStatus, useLumiaPassportOpen, useLumiaPassportRecoveryUserId, useLumiaPassportSession, useNicknameResolve, useSendTransaction, useSmartAccountTransactions, useTokenBalance, useTokenInfo, useTransactions, useUserOpStatus, wagmiConfig };
+export { type AccountSession, Address, type AddressProps, type Asset, ConnectWalletButton, type ConnectWalletButtonProps, ErrorCodes, type FingerprintVerificationResult, Hash, type HashProps, KeyshareBackupMenu as KeyshareBackup, LUMIA_EXPLORER_URL, LumiaLogo, type LumiaPassportCallbacks, type LumiaPassportConfig, LumiaPassportError, LumiaPassportProvider, type LumiaPassportProviderProps, LumiaPassportSessionProvider, LumiaRainbowKitProvider, LumiaWagmiProvider, type NicknameAvailability, type NicknameAvatar, type NicknameChangeResult, type NicknameInfo, type NicknameResolution, type NicknameResolveRequest, type NicknameResolvedTarget, type NicknameValidationResult, PageKey, type PageOpenParams, type ProviderDetail, type SendTransactionParams, type SendTransactionResult, type SignTypedDataParams, ThemeToggle, type TokenBalance, type Transaction, TransactionsList, type TypedDataDomain, type TypedDataField, type UpdateProfileRequest, type UseLogoutReturn, type UseNicknameResolveOptions, type UseNicknameResolveResult, type UseSendTransactionReturn, type UseUserOpStatusOptions, type UseUserOpStatusReturn, type UserOpMempool, type UserOpReceipt, type SendTransactionParams$1 as UserOpSendTransactionParams, type UserOpState, UserOpStatus, type UserOpStatusProps, type UserOperation, type UserProfile, UserRejectedError, type WalletReadyStatus, createLumiaPassportError, deployAccount, destroyIframeManager, generateFingerprint, getIframeManager, getUserProfile, looksLikeNickname, lumiaBeam, prepareUserOperation, queryClient, sendUserOperation, signTypedData, updateUserProfile, useAssets, useLogout, useLumiaPassportAccountSession, useLumiaPassportAddress, useLumiaPassportBalance, useLumiaPassportColorMode, useLumiaPassportConfig, useLumiaPassportError, useLumiaPassportHasServerVault, useLumiaPassportIFrameReady, useLumiaPassportIsMobileView, useLumiaPassportLinkedProfiles, useLumiaPassportLoadingStatus, useLumiaPassportOpen, useLumiaPassportRecoveryUserId, useLumiaPassportSession, useNicknameResolve, useSendTransaction, useSmartAccountTransactions, useTokenBalance, useTokenInfo, useTransactions, useUserOpStatus, verifyFingerprint, verifyFingerprintDetailed, wagmiConfig };