hadv / hadv/ethaura

Implement Web3Auth MFA Backup Share (ShareC) for Account Recovery

Open
#131 0 comments 0 reactions 0 assignees View on GitHub
⛨ security enhancement web3auth
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.