Implement Web3Auth MFA Backup Share (ShareC) for Account Recovery
- Dominant language
- JavaScript
- Stars
- 2
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## 🎯 Objective
Implement Web3Auth's built-in Multi-Factor Authentication (MFA) system to enable users to create and download backup shares (ShareC) for account recovery, eliminating dependency on Web3Auth service availability.
## 📋 Background
Currently, EthAura users are heavily dependent on Web3Auth service for account access. If Web3Auth shuts down, users cannot:
- Login to their accounts
- Create new accounts
- Sign transactions (unless they have guardians set up)
Web3Auth already provides a built-in solution through their MFA system using **2-of-3 Shamir Secret Sharing**:
- **ShareA (Device)**: Stored encrypted in browser storage
- **ShareB (Social)**: Managed by Web3Auth's MPC network
- **ShareC (Backup)**: Recovery share that users can download/save
## ✅ Solution
Leverage Web3Auth's existing `mfaSettings` and `backUpShareFactor` to allow users to:
1. Generate a backup share during/after account creation
2. Download the backup share as a recovery phrase
3. Recover their account using the backup share if Web3Auth becomes unavailable
## 🛠️ Implementation Tasks
### 1. Update Web3AuthContext Configuration
**File**: `frontend/src/contexts/Web3AuthContext.jsx`
- [ ] Add `mfaSettings` to Web3Auth initialization
- [ ] Enable `deviceShareFactor` (mandatory)
- [ ] Enable `backUpShareFactor` (mandatory) - this is ShareC
- [ ] Enable `socialBackupFactor` (optional)
- [ ] Configure priority order for MFA factors
```javascript
import { MFA_FACTOR } from '@web3auth/base';
const web3authInstance = new Web3Auth({
clientId: import.meta.env.VITE_WEB3AUTH_CLIENT_ID,
web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_DEVNET,
chainConfig,
privateKeyProvider,
mfaSettings: {
[MFA_FACTOR.DEVICE]: {
enable: true,
priority: 1,
mandatory: true,
},
[MFA_FACTOR.BACKUP_SHARE]: {
enable: true,
priority: 2,
mandatory: true, // Force users to create backup
},
[MFA_FACTOR.SOCIAL_BACKUP]: {
enable: true,
priority: 3,
mandatory: false,
},
},
});
```
### 2. Add MFA Setup Trigger
**File**: `frontend/src/contexts/Web3AuthContext.jsx`
- [ ] Add `enableMFA()` method to context
- [ ] Export method for use in components
```javascript
const enableMFA = async () => {
if (!web3auth) {
throw new Error('Web3Auth not initialized');
}
try {
await web3auth.enableMFA();
console.log('✅ MFA enabled successfully');
} catch (error) {
console.error('Error enabling MFA:', error);
throw error;
}
};
// Add to context value
const value = {
// ... existing values
enableMFA,
};
```
### 3. Create Backup Share Setup Component
**File**: `frontend/src/components/BackupShareSetup.jsx` (new file)
- [ ] Create UI component to prompt users to set up backup share
- [ ] Add clear instructions on saving the backup share securely
- [ ] Show success message after backup share is created
- [ ] Add warning about importance of backup share
### 4. Integrate into Account Creation Flow
**File**: `frontend/src/components/AccountManager.jsx`
- [ ] Prompt users to set up MFA after account creation
- [ ] Show backup share setup UI
- [ ] Add option to skip (with warning) or set up later
### 5. Add Settings UI for MFA Management
**File**: `frontend/src/screens/SettingsScreen.jsx`
- [ ] Add "Backup & Recovery" section
- [ ] Show MFA status (enabled/disabled)
- [ ] Add button to enable MFA if not already enabled
- [ ] Add button to view/download backup share again
- [ ] Add instructions for recovery process
### 6. Update Documentation
- [ ] Update `docs/WEB3AUTH_INTEGRATION.md` with MFA setup instructions
- [ ] Update `docs/RECOVERY_GUIDE.md` with backup share recovery process
- [ ] Add FAQ section about backup shares
- [ ] Document the recovery process step-by-step
### 7. Testing
- [ ] Test MFA setup flow on Sapphire Devnet (free tier)
- [ ] Test backup share download
- [ ] Test account recovery using backup share
- [ ] Test recovery with different combinations (Device + Backup, Social + Backup)
- [ ] Verify backup share works if Web3Auth service is unavailable
## 📊 MFA Factors Available
| Factor | Key | Description | Priority |
|--------|-----|-------------|----------|
| Device Share | `deviceShareFactor` | Stored in browser storage | 1 (mandatory) |
| **Backup Share** | **`backUpShareFactor`** | **Recovery phrase to download** | **2 (mandatory)** |
| Social Backup | `socialBackupFactor` | Another social login | 3 (optional) |
| Password | `passwordFactor` | Password-based auth | 4 (optional) |
| Passkeys | `passkeysFactor` | WebAuthn passkeys | 5 (optional) |
| Authenticator | `authenticatorFactor` | TOTP (Google Authenticator) | 6 (optional) |
## 🔒 Security Benefits
1. **Reduced Web3Auth Dependency**: Users can recover accounts even if Web3Auth shuts down
2. **Multiple Recovery Options**: Any 2 of 3 shares can recover the account
3. **User Control**: Users have full control over their backup share
4. **Standard Cryptography**: Uses proven Shamir Secret Sharing (2-of-3 threshold)
## ⚠️ Important Notes
- **Pricing**: MFA is a paid feature (Scale Plan required for production)
- **Free Tier**: Available for free on Sapphire Devnet for testing
- **Current SDK**: EthAura uses `@web3auth/modal` v9.7.0 which supports MFA
- **No Custom Implementation Needed**: Web3Auth handles all SSS cryptography
## 📚 References
- [Web3Auth MFA Documentation](https://docs.metamask.io/embedded-wallets/sdk/js/advanced/mfa/)
- [Web3Auth Infrastructure](https://web3auth.io/docs/infrastructure/)
- [MFA Factors Reference](https://docs.metamask.io/embedded-wallets/sdk/js/advanced/mfa/#mfa-factors)
## 🎯 Success Criteria
- [ ] Users are prompted to create backup share after account creation
- [ ] Users can download their backup share as a recovery phrase
- [ ] Users can recover their account using backup share + device share
- [ ] Users can recover their account using backup share + social share
- [ ] Clear documentation on backup and recovery process
- [ ] UI shows MFA status and backup share status
## 💡 Future Enhancements
- Add encrypted email delivery of backup share (optional)
- Support multiple backup methods (download, print, email)
- Add backup share verification step
- Implement backup share health check/reminder system
Contributor guide
Assessment
This issue has not been assessed yet.