@lumiapassport/ui-kit 1.0.2 → 1.2.0

package/README.md

@@ -0,0 +1,434 @@
+# @lumiapassport/ui-kit
+
+React UI components and hooks for Lumia Passport - a secure, user-friendly authentication and Account Abstraction wallet solution with MPC (Multi-Party Computation) key management.
+
+## Features
+
+- 🔐 **Secure Authentication** - Multiple auth methods: Email, Passkey, Telegram, Wallet connect
+- 🔑 **MPC Key Management** - Distributed key generation with iframe isolation
+- 💼 **Account Abstraction** - ERC-4337 compliant smart contract wallets
+- 🎨 **Pre-built UI Components** - Ready-to-use React components with customizable themes
+- ⚡ **Easy Integration** - Just wrap your app with `LumiaPassportProvider`
+
+## Installation
+
+```bash
+npm install @lumiapassport/ui-kit @lumiapassport/core
+# or
+pnpm add @lumiapassport/ui-kit @lumiapassport/core
+# or
+yarn add @lumiapassport/ui-kit @lumiapassport/core
+```
+
+### Peer Dependencies
+
+The following packages are required as peer dependencies:
+
+```bash
+npm install react react-dom viem wagmi @tanstack/react-query
+```
+
+## Quick Start
+
+### 1. Wrap your app with `LumiaPassportProvider`
+
+```tsx
+import { LumiaPassportProvider } from '@lumiapassport/ui-kit';
+import '@lumiapassport/ui-kit/dist/styles.css';
+
+function App() {
+  return (
+    <LumiaPassportProvider
+      config={{
+        projectId: 'your-project-id', // Get from Lumia Passport Dashboard
+        services: {
+          tssUrl: 'https://api.lumiapassport.com/tss',
+          bundlerUrl: 'https://api.lumiapassport.com/rundler',
+          shareVaultUrl: 'https://api.lumiapassport.com/vault',
+        }
+      }}
+    >
+      <YourApp />
+    </LumiaPassportProvider>
+  );
+}
+```
+
+### 2. Add the Connect Button
+
+```tsx
+import { ConnectWalletButton } from '@lumiapassport/ui-kit';
+
+function YourApp() {
+  return (
+    <div>
+      <h1>My App</h1>
+      <ConnectWalletButton />
+    </div>
+  );
+}
+```
+
+That's it! The `ConnectWalletButton` provides a complete authentication UI with wallet management.
+
+## Configuration Options
+
+### Basic Configuration
+
+```tsx
+<LumiaPassportProvider
+  config={{
+    projectId: 'your-project-id', // Required
+
+    // Optional: Service URLs (defaults to production)
+    services: {
+      tssUrl: 'https://api.lumiapassport.com/tss',
+      bundlerUrl: 'https://api.lumiapassport.com/rundler',
+      shareVaultUrl: 'https://api.lumiapassport.com/vault',
+      iframeUrl: 'https://auth.lumiapassport.com',
+    },
+
+    // Optional: Custom RPC and network
+    rpcUrl: 'https://beam-rpc.lumia.org',
+    explorerUrl: 'https://beam-explorer.lumia.org',
+
+    // Optional: Custom smart contract addresses
+    aaFactoryAddress: '0x...',
+    paymasterAddress: '0x...',
+  }}
+>
+```
+
+### Advanced Configuration
+
+```tsx
+<LumiaPassportProvider
+  config={{
+    projectId: 'your-project-id',
+
+    // Authentication providers
+    authProviders: {
+      email: true,      // Email OTP
+      passkey: true,    // Passkey/WebAuthn
+      telegram: true,   // Telegram Mini App
+      wallet: true,     // External wallet connection
+    },
+
+    // UI customization
+    theme: {
+      mode: 'dark',           // 'light' | 'dark' | 'auto'
+      primaryColor: '#6366f1', // Custom brand color
+    },
+
+    // Features
+    features: {
+      backup: true,           // Enable key backup/recovery
+      mpcSecurity: true,      // Enable MPC iframe isolation
+    },
+  }}
+>
+```
+
+## Using Hooks
+
+### useAuth - Authentication State
+
+```tsx
+import { useAuth } from '@lumiapassport/ui-kit';
+
+function MyComponent() {
+  const {
+    user,           // Current user info
+    isAuthenticated, // Auth status
+    login,          // Login function
+    logout,         // Logout function
+    loading,        // Loading state
+  } = useAuth();
+
+  if (loading) return <div>Loading...</div>;
+
+  if (!isAuthenticated) {
+    return <button onClick={() => login()}>Sign In</button>;
+  }
+
+  return (
+    <div>
+      <p>Welcome, {user.userId}</p>
+      <button onClick={() => logout()}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+### useWallet - Wallet Operations
+
+```tsx
+import { useWallet } from '@lumiapassport/ui-kit';
+
+function SendTransaction() {
+  const { address, sendTransaction, balance } = useWallet();
+
+  const handleSend = async () => {
+    const hash = await sendTransaction({
+      to: '0x...',
+      value: '0.1', // ETH amount
+    });
+    console.log('Transaction hash:', hash);
+  };
+
+  return (
+    <div>
+      <p>Address: {address}</p>
+      <p>Balance: {balance} ETH</p>
+      <button onClick={handleSend}>Send Transaction</button>
+    </div>
+  );
+}
+```
+
+### useSendTransaction - Send Transactions
+
+```tsx
+import { useSendTransaction } from '@lumiapassport/ui-kit';
+
+function TransactionExample() {
+  const { sendTransaction, isPending } = useSendTransaction();
+
+  const handleSend = async () => {
+    try {
+      const userOpHash = await sendTransaction({
+        to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+        value: '1000000000000000000', // 1 ETH in wei
+        data: '0x', // Optional contract call data
+      });
+      console.log('UserOp hash:', userOpHash);
+    } catch (error) {
+      console.error('Transaction failed:', error);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleSend} disabled={isPending}>
+        {isPending ? 'Sending...' : 'Send Transaction'}
+      </button>
+    </div>
+  );
+}
+```
+
+### prepareUserOperation - Prepare for Backend Submission
+
+```tsx
+import { prepareUserOperation, useLumiaSession } from '@lumiapassport/ui-kit';
+
+function BackendSubmissionExample() {
+  const { session } = useLumiaSession();
+
+  const handlePrepare = async () => {
+    if (!session) return;
+
+    // Prepare and sign UserOp without sending to bundler
+    const { userOp, userOpHash } = await prepareUserOperation(
+      session,
+      '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb', // to
+      '1000000000000000000', // 1 ETH in wei
+      '0x', // data
+      'standard', // fee type: 'economy' | 'standard' | 'fast'
+      'v0.7' // EntryPoint version
+    );
+
+    // Send to backend for validation and submission
+    await fetch('/api/submit-transaction', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        userOp,
+        userOpHash,
+        ownerAddress: session.ownerAddress // for signature verification
+      }),
+    });
+  };
+
+  return (
+    <button onClick={handlePrepare}>
+      Prepare & Send to Backend
+    </button>
+  );
+}
+```
+
+**Backend example (using @lumiapassport/core):**
+
+```typescript
+import { sendUserOperationRaw } from '@lumiapassport/core';
+import { recoverAddress } from 'viem';
+
+// Receive from frontend
+const { userOp, userOpHash, ownerAddress } = await request.json();
+
+// Verify signature
+const recoveredAddress = await recoverAddress({
+  hash: userOpHash,
+  signature: userOp.signature,
+});
+
+if (recoveredAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
+  throw new Error('Invalid signature');
+}
+
+// Submit to bundler
+const txHash = await sendUserOperationRaw(userOp);
+return { success: true, txHash };
+```
+
+## Components
+
+### ConnectWalletButton
+
+Pre-built button with authentication modal.
+
+```tsx
+<ConnectWalletButton
+  className="custom-class"
+  onConnect={(user) => console.log('Connected:', user)}
+  onDisconnect={() => console.log('Disconnected')}
+/>
+```
+
+### Custom Authentication Flow
+
+```tsx
+import { AuthModal, useAuthModal } from '@lumiapassport/ui-kit';
+
+function CustomAuth() {
+  const { openAuth } = useAuthModal();
+
+  return (
+    <div>
+      <button onClick={() => openAuth()}>
+        Custom Sign In
+      </button>
+      <AuthModal />
+    </div>
+  );
+}
+```
+
+## Authentication Methods
+
+### Email OTP
+
+Users receive a one-time code via email.
+
+```tsx
+// Configured by default, no additional setup needed
+```
+
+### Passkey (WebAuthn)
+
+Secure biometric authentication with device passkeys.
+
+```tsx
+// Configured by default
+// Users can register passkey after initial login
+```
+
+### Telegram Mini App
+
+Authentication via Telegram for mini apps.
+
+```tsx
+// Requires Telegram bot configuration
+// Set in config:
+config={{
+  telegram: {
+    botName: 'your_bot_name',
+  }
+}}
+```
+
+### External Wallet
+
+Connect existing wallets (MetaMask, WalletConnect, etc.).
+
+```tsx
+// Configured by default
+// Uses RainbowKit for wallet connections
+```
+
+## Styling
+
+### Using Built-in Themes
+
+```tsx
+import '@lumiapassport/ui-kit/dist/styles.css';
+
+<LumiaPassportProvider
+  config={{
+    projectId: 'your-project-id',
+    theme: {
+      mode: 'dark', // or 'light', 'auto'
+    }
+  }}
+>
+```
+
+### Custom Styling
+
+Override CSS variables for custom branding:
+
+```css
+.lumia-scope {
+  --lumia-primary: #6366f1;
+  --lumia-background: #0f172a;
+  --lumia-surface: #1e293b;
+  --lumia-text-primary: #f8fafc;
+  --lumia-text-secondary: #cbd5e1;
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```tsx
+import type {
+  LumiaPassportConfig,
+  User,
+  AuthProvider,
+  WalletInfo,
+} from '@lumiapassport/ui-kit';
+```
+
+## Examples
+
+Check out the `/examples` directory for complete working examples:
+
+- **React + Vite** - Modern React setup with Vite
+- **Next.js** - Next.js App Router integration
+- **React + TypeScript** - Full TypeScript example
+
+## Security
+
+- 🔒 **MPC Key Management** - Keys are split between client and server using threshold cryptography
+- 🏝️ **Iframe Isolation** - Sensitive operations run in isolated iframe context
+- 🔐 **No Private Key Exposure** - Private keys never exist in complete form on client
+- ✅ **Non-custodial** - Users maintain full control of their accounts
+
+## Need Help?
+
+- 📖 [Documentation](https://docs.lumiapassport.com)
+- 💬 [Discord Community](https://discord.gg/lumia)
+- 🐛 [Report Issues](https://github.com/lumiachain/lumia-passport-sdk/issues)
+- 📧 [Email Support](mailto:support@lumia.org)
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Links
+
+- [Website](https://lumiapassport.com)
+- [GitHub](https://github.com/lumiachain/lumia-passport-sdk)
+- [NPM Package](https://www.npmjs.com/package/@lumiapassport/ui-kit)

package/dist/iframe/main.js

@@ -783,7 +783,7 @@ var SecureMessenger = class {
       return;
     }
     const response = {
-      type: "RESPONSE",
+      type: "LUMIA_PASSPORT_RESPONSE",
       messageId,
       timestamp: Date.now(),
       data
@@ -800,7 +800,7 @@ var SecureMessenger = class {
       return;
     }
     const response = {
-      type: "ERROR",
+      type: "LUMIA_PASSPORT_ERROR",
       messageId,
       timestamp: Date.now(),
       error
@@ -1597,7 +1597,7 @@ var TokenRefreshApiClient = class {
       }, 3e4);
       const messageHandler = (event) => {
         const message = event.data;
-        if (message && message.type === "TOKEN_REFRESHED" && message.messageId === messageId) {
+        if (message && message.type === "LUMIA_PASSPORT_TOKEN_REFRESHED" && message.messageId === messageId) {
           cleanup();
           if (message.accessToken) {
             console.log("[iframe][TokenRefresh] \u2705 Received new token from parent");
@@ -1619,14 +1619,14 @@ var TokenRefreshApiClient = class {
       if (window.parent && window.parent !== window) {
         window.parent.postMessage(
           {
-            type: "REQUEST_NEW_TOKEN",
+            type: "LUMIA_PASSPORT_REQUEST_NEW_TOKEN",
             messageId,
             timestamp: Date.now()
           },
           "*"
           // Parent will validate origin
         );
-        console.log("[iframe][TokenRefresh] \u{1F4E4} Sent REQUEST_NEW_TOKEN to parent");
+        console.log("[iframe][TokenRefresh] \u{1F4E4} Sent LUMIA_PASSPORT_REQUEST_NEW_TOKEN to parent");
       } else {
         cleanup();
         reject(new Error("No parent window available"));
@@ -2390,7 +2390,7 @@ var SigningManager = class extends TokenRefreshApiClient {
    */
   showIframe() {
     if (window.parent !== window) {
-      window.parent.postMessage({ type: "SHOW_IFRAME", timestamp: Date.now() }, "*");
+      window.parent.postMessage({ type: "LUMIA_PASSPORT_SHOW_IFRAME", timestamp: Date.now() }, "*");
       console.log("[iframe][Sign] Requested parent to show iframe");
     }
   }
@@ -2399,7 +2399,7 @@ var SigningManager = class extends TokenRefreshApiClient {
    */
   hideIframe() {
     if (window.parent !== window) {
-      window.parent.postMessage({ type: "HIDE_IFRAME", timestamp: Date.now() }, "*");
+      window.parent.postMessage({ type: "LUMIA_PASSPORT_HIDE_IFRAME", timestamp: Date.now() }, "*");
       console.log("[iframe][Sign] Requested parent to hide iframe");
     }
   }
@@ -2511,7 +2511,7 @@ var AuthorizationManager = class {
    */
   showIframe() {
     if (window.parent !== window) {
-      window.parent.postMessage({ type: "SHOW_IFRAME", timestamp: Date.now() }, "*");
+      window.parent.postMessage({ type: "LUMIA_PASSPORT_SHOW_IFRAME", timestamp: Date.now() }, "*");
       console.log("[iframe][Auth] Requested parent to show iframe");
     }
   }
@@ -2520,7 +2520,7 @@ var AuthorizationManager = class {
    */
   hideIframe() {
     if (window.parent !== window) {
-      window.parent.postMessage({ type: "HIDE_IFRAME", timestamp: Date.now() }, "*");
+      window.parent.postMessage({ type: "LUMIA_PASSPORT_HIDE_IFRAME", timestamp: Date.now() }, "*");
       console.log("[iframe][Auth] Requested parent to hide iframe");
     }
   }
@@ -2655,7 +2655,7 @@ var IframeWallet = class {
     if (window.parent !== window) {
       window.parent.postMessage(
         {
-          type: "IFRAME_READY",
+          type: "LUMIA_PASSPORT_IFRAME_READY",
           timestamp: Date.now()
         },
         "*"
@@ -2718,7 +2718,7 @@ var IframeWallet = class {
     this.messenger.sendResponse(
       messageId,
       {
-        type: "SDK_AUTH_SUCCESS",
+        type: "LUMIA_PASSPORT_SDK_AUTH_SUCCESS",
         sessionToken
       },
       origin
@@ -2753,7 +2753,7 @@ var IframeWallet = class {
     this.messenger.sendResponse(
       messageId,
       {
-        type: "AUTH_SUCCESS",
+        type: "LUMIA_PASSPORT_AUTH_SUCCESS",
         userId,
         address
       },
@@ -2784,7 +2784,7 @@ var IframeWallet = class {
       this.messenger.sendResponse(
         messageId,
         {
-          type: "DKG_SUCCESS",
+          type: "LUMIA_PASSPORT_DKG_SUCCESS",
           ownerAddress: result.ownerAddress
         },
         origin
@@ -2817,7 +2817,7 @@ var IframeWallet = class {
       this.messenger.sendResponse(
         messageId,
         {
-          type: "SIGNATURE",
+          type: "LUMIA_PASSPORT_SIGNATURE",
           signature
         },
         origin
@@ -2838,7 +2838,7 @@ var IframeWallet = class {
     this.messenger.sendResponse(
       messageId,
       {
-        type: "ADDRESS",
+        type: "LUMIA_PASSPORT_ADDRESS",
         address
       },
       origin
@@ -2855,7 +2855,7 @@ var IframeWallet = class {
     this.messenger.sendResponse(
       messageId,
       {
-        type: "KEYSHARE_STATUS",
+        type: "LUMIA_PASSPORT_KEYSHARE_STATUS",
         hasKeyshare,
         address
       },
@@ -2876,7 +2876,7 @@ var IframeWallet = class {
     this.messenger.sendResponse(
       messageId,
       {
-        type: "TRUSTED_APPS_LIST",
+        type: "LUMIA_PASSPORT_TRUSTED_APPS_LIST",
         apps: trustedApps
       },
       origin
@@ -2896,7 +2896,7 @@ var IframeWallet = class {
     this.messenger.sendResponse(
       messageId,
       {
-        type: "TRUSTED_APP_REMOVED",
+        type: "LUMIA_PASSPORT_TRUSTED_APP_REMOVED",
         success: true
       },
       origin