feat(wallets): add Web3Auth provider with secure key handling (#413)

* feat(*): add Web3Auth wallet support

introduce Web3Auth wallet integration with secure key handling. includes `SecureKeyContainer`, automatic memory zeroing, and enhanced cryptographic features. added relevant utility tests and optional peer dependencies.

* feat(use-wallet): add tests for deriveAlgorandAccountFromEd25519

introduce comprehensive test coverage for `deriveAlgorandAccountFromEd25519`, including Web3Auth-style key handling, key validation, transaction signing, and integration with `SecureKeyContainer`. added utility functions to enhance test clarity and realism.

* feat(*): enhance Web3Auth integration and update dependencies

improve Web3Auth integration with support for `CommonPrivateKeyProvider`, updated chain configuration for Algorand, and conditional inclusion based on `VITE_WEB3AUTH_CLIENT_ID`. refine error handling and logging for missing dependencies. update packages and add optional peer dependencies for Web3Auth. adjust test suite to reflect changes.

* feat(*): add support for Web3Auth custom authentication flows

extend Web3Auth wallet to support custom JWT-based authentication, such as Firebase integration. implement `Single Factor Auth` (SFA) SDK with dynamic imports and conditional usage. update the `Connect` component to enable custom auth configuration in the UI. enhance test suite to cover new functionality. update dependencies to include `@web3auth/single-factor-auth`.

* feat(Connect): add Firebase authentication support

integrate Firebase authentication into the `Connect` component, enabling sign-in with Google and Firebase UID-based authentication for Web3Auth wallet connections. include dynamic handling of Firebase state changes, conditional authentication configuration in the UI, and enhanced error management. update dependencies with Firebase packages and related utilities.

* feat(FirebaseAuth): add reusable Firebase authentication component

introduce `FirebaseAuth` component for streamlined Firebase authentication functionality, supporting Google sign-in and email/password authentication flows. improve state management and error handling with user-friendly messages. update `Connect` component to integrate `FirebaseAuth`, removing redundant logic. include added styles for the new component and update dependencies with `firebaseui`.

* style: format codebase with Prettier for CI compliance

Run Prettier across the codebase to ensure all files meet formatting
standards and CI checks pass.

- Update .prettierignore to exclude CLAUDE.md and .claude/ directory
- Format imports in firebase.ts for better readability
- Adjust comment formatting in web3auth.test.ts
- Add missing newline at end of secure-key.ts

* chore(deps): add tweetnacl for ed25519 key derivation

Add `tweetnacl` as a devDependency to resolve TypeScript compilation
errors in secure-key.ts. The library is used for ed25519 keypair
derivation in the Web3Auth wallet implementation, specifically for
converting 32-byte ed25519 seeds into Algorand-compatible accounts.

* chore: release v4.4.0-beta.0

* feat(Web3Auth): implement lazy authentication and automatic session refresh

introduce lazy authentication mechanism that defers Web3Auth connection until `signTransactions()` is called. add automatic session refresh for Single Factor Auth (SFA) via `getAuthCredentials` callback. implement separate reconnection flows for SFA and modal authentication. enhance security by verifying address matches after re-authentication and disconnecting wallet if user changes. update session resume to restore cached address without initializing Web3Auth. extend test suite with lazy authentication scenarios covering session expiry, re-authentication flows, and modal cancellation.

* chore: release v4.4.0-beta.1

* refactor(react-ts): separate Web3Auth modal and Firebase SFA flows

Restructure Web3Auth authentication in the example to clearly distinguish
between the two connection methods:

1. Standard Modal SDK - Uses Web3Auth's built-in UI for social logins
2. Firebase SFA - Uses Firebase JWT for single-factor authentication

UI changes:
- Replace checkbox toggle with separate "or connect with Firebase" section
- Add section divider styling for visual separation
- Fix button text wrapping with `white-space: nowrap`
- Add `input[type='password']` to global input styles for consistency
- Remove redundant custom styles for auth form inputs and buttons

This separation makes the two authentication flows explicit and easier to
understand for developers reviewing the example.

* fix(Web3Auth): log actual error when package loading fails

Include the caught error in the log output to help diagnose
dynamic import failures (e.g., missing dependencies or bundler
polyfill issues).

* feat(examples): add Web3Auth and Firebase authentication

Add Web3Auth wallet provider with Firebase Single Factor Authentication
(SFA) support to all remaining example applications.

## Changes per example

- nextjs: Add firebase.ts, FirebaseAuth.tsx, update Connect.tsx and providers.tsx
- vue-ts: Add firebase.ts, FirebaseAuth.vue, update Connect.vue and main.ts
- nuxt: Add firebase.ts, FirebaseAuth.vue, polyfills.client.ts for Web3Auth compatibility
- solid-ts: Add firebase.ts, FirebaseAuth.tsx, update Connect.tsx and App.tsx
- svelte-ts: Add firebase.ts, FirebaseAuth.svelte, update connect.svelte and +layout.svelte
- vanilla-ts: Add firebase.ts, FirebaseAuthComponent.ts, update WalletComponent.ts and main.ts

## Additional fixes

- Add password input styling to vue-ts and solid-ts global CSS
- Add .env.example files with Web3Auth and Firebase configuration templates
- Nuxt requires manual polyfills plugin due to vite-plugin-node-polyfills incompatibility

* refactor(examples): simplify Web3Auth demos by removing custom auth complexity

The Firebase authentication integrations add significant complexity to what
should be simple, focused wallet integration demos. This simplifies all
example applications to use only the Web3Auth modal for social login,
providing a cleaner developer experience.

Changes:
- Remove Firebase SDK dependency from all 7 example apps
- Remove Firebase auth components and utility files
- Remove Firebase-related CSS styles
- Simplify .env.example files to only include Web3Auth client ID
- Update Connect components to remove Firebase SFA flow

* docs: add Web3Auth wallet provider documentation

Document the Web3Auth provider in the getting-started guides, including:

- Installation instructions for required dependencies: @web3auth/modal,
  @web3auth/base, and @web3auth/base-provider
- Configuration options for the modal-based authentication flow
- Optional parameters: web3AuthNetwork, loginProvider, uiConfig
- Custom Authentication section explaining Single Factor Auth (SFA)
  approach with note about additional @web3auth/single-factor-auth
  dependency
- Links to Web3Auth dashboard and documentation

* style(examples): fix Prettier formatting

Apply Prettier formatting fixes to resolve CI failures.

- Remove trailing blank lines from CSS files
- Collapse Vue template attributes to single line where appropriate

* chore(webpack): add Web3Auth packages to webpack fallback

Add missing Web3Auth peer dependencies to the webpack fallback
configuration to prevent build errors when these optional packages
are not installed.

- `@web3auth/base`
- `@web3auth/base-provider`
- `@web3auth/modal`
- `@web3auth/single-factor-auth`

---------

Co-authored-by: Doug Richar <drichar@gmail.com>

Author: pbennett

.prettierignore

@@ -11,3 +11,7 @@ docs/**
 
 # Generated Svelte files
 **/.svelte-kit
+
+# Project files
+CLAUDE.md
+.claude/**

CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+**Important**: Keep this document updated when making significant changes to the codebase, such as adding new commands, changing architecture patterns, introducing new directories, or modifying the build/test setup.
+
+## Project Overview
+
+@txnlab/use-wallet is a framework-agnostic Algorand wallet integration library with reactive framework adapters for React, Vue, SolidJS, and Svelte. It enables dApps to connect to various Algorand wallets, sign transactions, and manage wallet sessions.
+
+## Commands
+
+### Development
+```bash
+pnpm install              # Install dependencies
+pnpm dev                  # Watch mode for all packages
+pnpm build:packages       # Build all packages
+pnpm build                # Build packages and examples
+```
+
+### Testing
+```bash
+pnpm test                                         # Run all tests
+pnpm --filter @txnlab/use-wallet test             # Run core package tests
+pnpm --filter @txnlab/use-wallet test:watch       # Watch mode for core tests
+```
+
+### Linting & Type Checking
+```bash
+pnpm lint                 # Lint all packages
+pnpm typecheck            # Type check all packages
+pnpm prettier             # Check formatting
+```
+
+### Running Examples
+```bash
+pnpm example:react        # React example
+pnpm example:vue          # Vue example
+pnpm example:solid        # SolidJS example
+pnpm example:svelte       # Svelte example
+pnpm example:nextjs       # Next.js example
+pnpm example:nuxt         # Nuxt example
+pnpm example:ts           # Vanilla TypeScript example
+```
+
+## Architecture
+
+### Package Structure (pnpm monorepo)
+
+- **packages/use-wallet** (`@txnlab/use-wallet`) - Core framework-agnostic library
+- **packages/use-wallet-react** (`@txnlab/use-wallet-react`) - React adapter
+- **packages/use-wallet-vue** (`@txnlab/use-wallet-vue`) - Vue adapter
+- **packages/use-wallet-solid** (`@txnlab/use-wallet-solid`) - SolidJS adapter
+- **packages/use-wallet-svelte** (`@txnlab/use-wallet-svelte`) - Svelte adapter
+
+Framework adapters depend on the core package via `workspace:*` and re-export all core exports.
+
+### Core Package Architecture
+
+**State Management**: Uses `@tanstack/store` for reactive state. State includes:
+- `wallets`: Map of wallet IDs to their connection state (accounts, active account)
+- `activeWallet`: Currently active wallet ID
+- `activeNetwork`: Current network (mainnet, testnet, etc.)
+- `algodClient`: Algorand SDK client instance
+
+**Key Classes**:
+- `WalletManager` (`src/manager.ts`): Orchestrates wallet initialization, network configuration, and state persistence. Entry point for configuring the library.
+- `BaseWallet` (`src/wallets/base.ts`): Abstract base class all wallet implementations extend. Defines the wallet interface: `connect()`, `disconnect()`, `resumeSession()`, `signTransactions()`.
+
+**Wallet Implementations** (`src/wallets/`): Each wallet provider (Pera, Defly, Exodus, WalletConnect, KMD, Web3Auth, etc.) has its own implementation extending `BaseWallet`. Wallet SDKs are peer dependencies, allowing users to install only what they need.
+
+**Secure Key Utilities** (`src/secure-key.ts`): For wallets that handle raw private keys (Web3Auth, Mnemonic), provides `SecureKeyContainer` for safe key handling with automatic memory zeroing. Keys are never persisted and are cleared immediately after use.
+
+**State Persistence**: Wallet state is persisted to localStorage under key `@txnlab/use-wallet:v4`.
+
+### Framework Adapter Pattern
+
+Each adapter provides:
+1. A context provider component (e.g., `WalletProvider` in React)
+2. Hooks/composables that subscribe to store state and provide reactive wallet data
+3. Re-exports of all core types and classes
+
+Example: React's `useWallet()` hook uses `@tanstack/react-store` to subscribe to state changes and returns reactive wallet data plus signing methods.
+
+## Key Types
+
+- `WalletId`: Enum of supported wallet IDs (PERA, DEFLY, EXODUS, WALLETCONNECT, KMD, WEB3AUTH, MAGIC, etc.)
+- `WalletAccount`: `{ name: string, address: string }`
+- `SupportedWallet`: Either a `WalletId` string or a config object `{ id, options?, metadata? }`
+
+## ESLint Configuration
+
+Uses TypeScript ESLint with `@typescript-eslint/no-explicit-any` disabled. Unused variables prefixed with `_` are allowed.

docs/getting-started/installation.md

@@ -367,6 +367,34 @@ bun add magic-sdk @magic-ext/algorand
 {% endtab %}
 {% endtabs %}
 
+#### Web3Auth
+
+{% tabs %}
+{% tab title="npm" %}
+```bash
+npm install @web3auth/modal @web3auth/base @web3auth/base-provider
+```
+{% endtab %}
+
+{% tab title="yarn" %}
+```bash
+yarn add @web3auth/modal @web3auth/base @web3auth/base-provider
+```
+{% endtab %}
+
+{% tab title="pnpm" %}
+```bash
+pnpm add @web3auth/modal @web3auth/base @web3auth/base-provider
+```
+{% endtab %}
+
+{% tab title="bun" %}
+```bash
+bun add @web3auth/modal @web3auth/base @web3auth/base-provider
+```
+{% endtab %}
+{% endtabs %}
+
 ### Webpack Configuration
 
 When using this library in a project that uses Webpack as its build tool, you may encounter "module not found" errors for optional dependencies of wallets you choose not to support. To resolve this, you can use the `webpackFallback` export.

docs/getting-started/supported-wallets.md

@@ -186,6 +186,58 @@ import { WalletId } from '@txnlab/use-wallet'
 * [Magic Website](https://magic.link)
 * [Magic Algorand Documentation](https://magic.link/docs/blockchains/other-chains/other/algorand)
 
+#### Web3Auth
+
+Social login authentication provider supporting Google, Facebook, Twitter, Discord, and other OAuth providers. Web3Auth enables users to sign in with familiar social accounts and derive an Algorand wallet from their authentication credentials. [Installation instructions](installation.md#web3auth).
+
+```typescript
+import { WalletId } from '@txnlab/use-wallet'
+
+// Basic usage with modal (shows social login options)
+{
+  id: WalletId.WEB3AUTH,
+  options: {
+    clientId: string // Required: from dashboard.web3auth.io
+  }
+}
+
+// With optional configuration
+{
+  id: WalletId.WEB3AUTH,
+  options: {
+    clientId: string               // Required: from dashboard.web3auth.io
+    web3AuthNetwork?: string       // Optional: 'sapphire_mainnet' (default) or 'sapphire_devnet'
+    loginProvider?: string         // Optional: skip modal and use specific provider (e.g., 'google', 'facebook')
+    uiConfig?: {                   // Optional: customize modal appearance
+      appName?: string
+      logoLight?: string
+      logoDark?: string
+      mode?: 'light' | 'dark' | 'auto'
+    }
+  }
+}
+```
+
+**Custom Authentication**
+
+Web3Auth also supports custom authentication flows using Single Factor Auth (SFA), allowing integration with existing authentication systems such as Firebase, Auth0, or custom JWT providers. This approach requires an additional dependency:
+
+```bash
+npm install @web3auth/single-factor-auth
+```
+
+This advanced use case requires:
+
+- Setting up a custom verifier in the [Web3Auth Dashboard](https://dashboard.web3auth.io)
+- Configuring the `verifier` option and `getAuthCredentials` callback
+- Managing authentication tokens and passing credentials to the `connect()` method
+
+For implementation details, refer to the [Web3Auth Single Factor Auth documentation](https://web3auth.io/docs/sdk/core-kit/sfa-web).
+
+* [Web3Auth Website](https://web3auth.io)
+* [Web3Auth Dashboard](https://dashboard.web3auth.io)
+* [Web3Auth Documentation](https://web3auth.io/docs)
+
 #### Biatec
 
 Open-source mobile wallet with community focus and WalletConnect support. [Installation instructions](installation.md#walletconnect).

examples/nextjs/.env.example

@@ -0,0 +1,2 @@
+# Web3Auth Client ID - get yours from https://dashboard.web3auth.io
+NEXT_PUBLIC_WEB3AUTH_CLIENT_ID=your_web3auth_client_id_here

examples/nextjs/package.json

@@ -15,12 +15,17 @@
     "@txnlab/use-wallet-react": "workspace:*",
     "@walletconnect/modal": "^2.7.0",
     "@walletconnect/sign-client": "^2.21.8",
+    "@web3auth/base": "^9.6.0",
+    "@web3auth/base-provider": "^9.6.0",
+    "@web3auth/modal": "^9.6.0",
+    "@web3auth/single-factor-auth": "^9.4.0",
     "algosdk": "3.4.0",
     "canonify": "2.1.1",
     "lute-connect": "^1.6.2",
     "next": "14.2.31",
     "react": "18.3.1",
-    "react-dom": "18.3.1"
+    "react-dom": "18.3.1",
+    "tweetnacl": "^1.0.3"
   },
   "devDependencies": {
     "@types/node": "20.11.30",

examples/nextjs/src/app/Connect.tsx

@@ -36,11 +36,12 @@ export function Connect() {
     return false
   }
 
-  const getConnectArgs = (wallet: Wallet) => {
+  const handleConnect = async (wallet: Wallet) => {
     if (isMagicLink(wallet)) {
-      return { email: magicEmail }
+      await wallet.connect({ email: magicEmail })
+    } else {
+      await wallet.connect()
     }
-    return undefined
   }
 
   const setActiveAccount = (event: React.ChangeEvent<HTMLSelectElement>, wallet: Wallet) => {
@@ -158,7 +159,7 @@ export function Connect() {
           <div className={styles.walletButtons}>
             <button
               type="button"
-              onClick={() => wallet.connect(getConnectArgs(wallet))}
+              onClick={() => handleConnect(wallet)}
               disabled={isConnectDisabled(wallet)}
             >
               Connect

examples/nextjs/src/app/globals.css

@@ -122,7 +122,8 @@ button:disabled {
 }
 
 input[type='text'],
-input[type='email'] {
+input[type='email'],
+input[type='password'] {
   border-radius: 8px;
   border: 1px solid #1a1a1a;
   padding: 0.6em 0.9em;
@@ -172,9 +173,133 @@ select {
   }
   input[type='text'],
   input[type='email'],
+  input[type='password'],
   select {
     background-color: #f9f9f9;
     color: #1a1a1a;
     border-color: #cacaca;
   }
 }
+
+/* Firebase Auth Styles */
+.firebase-auth-container {
+  display: flex;
+  flex-direction: column;
+  gap: 1em;
+  padding: 1em;
+  max-width: 300px;
+  margin: 0 auto;
+}
+
+.auth-tabs {
+  display: flex;
+  gap: 0.5em;
+}
+
+.auth-tabs button {
+  flex: 1;
+}
+
+.auth-tabs button.active {
+  border-color: #0071ff;
+}
+
+.auth-form {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75em;
+}
+
+.auth-divider {
+  display: flex;
+  align-items: center;
+  gap: 1em;
+  color: rgba(255, 255, 255, 0.5);
+}
+
+.auth-divider::before,
+.auth-divider::after {
+  content: '';
+  flex: 1;
+  height: 1px;
+  background: rgba(255, 255, 255, 0.2);
+}
+
+.google-signin-btn {
+  padding: 0.6em 1em;
+}
+
+.auth-error {
+  padding: 0.5em;
+  color: #ff6b6b;
+  background: rgba(255, 107, 107, 0.1);
+  border-radius: 4px;
+  font-size: 0.9em;
+}
+
+.firebase-user {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.6em;
+}
+
+.firebase-user-buttons {
+  display: flex;
+  gap: 0.5em;
+}
+
+.firebase-user-buttons button {
+  white-space: nowrap;
+}
+
+.firebase-user span {
+  font-size: 0.9em;
+  opacity: 0.8;
+}
+
+.firebase-auth {
+  margin-top: 0.5em;
+}
+
+.firebase-sfa-section {
+  width: 100%;
+  max-width: 300px;
+}
+
+.section-divider {
+  display: flex;
+  align-items: center;
+  gap: 1em;
+  margin: 1em 0;
+  color: rgba(255, 255, 255, 0.5);
+  font-size: 0.85em;
+}
+
+.section-divider::before,
+.section-divider::after {
+  content: '';
+  flex: 1;
+  height: 1px;
+  background: rgba(255, 255, 255, 0.2);
+}
+
+@media (prefers-color-scheme: light) {
+  .auth-divider {
+    color: rgba(0, 0, 0, 0.5);
+  }
+
+  .auth-divider::before,
+  .auth-divider::after {
+    background: rgba(0, 0, 0, 0.2);
+  }
+
+  .section-divider {
+    color: rgba(0, 0, 0, 0.5);
+  }
+
+  .section-divider::before,
+  .section-divider::after {
+    background: rgba(0, 0, 0, 0.2);
+  }
+}