Account Recovery Methods

​

Overview

​

Available Recovery Methods

1. Passkey Authentication - Standard login with biometrics/PIN
2. Trust Codes - Emergency recovery with 25-character codes
3. Device Approval - Login via another trusted device (requires existing session)

​

1. Passkey Authentication

​

Standard Login Flow

1. Navigate to login page
2. Enter your handle
3. Click “Continue with passkey”
4. Authenticate using biometrics (Touch ID, Face ID, Windows Hello) or device PIN
5. System verifies signature and creates session

​

With PRF Support (Preferred)

• Master key is encrypted with PRF output during registration
• On login, PRF output decrypts master key automatically
• No trust code needed for master key recovery
• Seamless experience across devices with synced passkeys

​

Without PRF Support

• Session is created successfully
• You’ll be prompted to recover master key using trust code
• Enter a trust code to decrypt your master key backup
• Master key is stored locally for future sessions

​

Adding Additional Passkeys

1. Log in to Dashboard
2. Navigate to Security
3. Click “Add a new passkey”
4. Follow browser prompts to create new passkey
5. Name it descriptively (e.g., “MacBook Pro Touch ID”)

​

2. Trust Code Recovery

​

What Are Trust Codes?

• Provided during registration (2 codes)
• Reusable (not consumed on use)
• Decrypt your master key backup
• Stored as SHA-256 hashes server-side

​

When to Use Trust Codes

• Device stolen/broken
• Passkeys not synced to other devices
• Need full account access immediately

• Logged in via passkey without PRF
• Need to decrypt existing data
• Don’t have master key stored locally

• Setting up first device in a new location
• No other active sessions to approve from
• Want to avoid waiting for approval timeout

​

Using Trust Codes

1. Start login flow with your handle
2. Click “Use a trust code”
3. Enter one of your saved codes (hyphens optional)
4. Provide device information
5. Master key backup is decrypted client-side
6. Session created with full access

​

3. Device Approval (Multi-Device Login)

​

How It Works

1. New device generates ephemeral ECDH key pair
2. New device requests approval via WebSocket/polling
3. Trusted device receives real-time notification
4. User reviews device info and approves/denies
5. Trusted device encrypts master key with shared secret
6. New device decrypts master key and creates session

​

Security Features

• Ephemeral ECDH key exchange (P-256 curve)
• Master key never transmitted in plaintext
• Only encrypted with short-lived shared secret

• Login requests expire after 5 minutes
• Prevents stale approval attempts
• Reduces attack window

• Device name and type
• Browser and operating system
• IP address and timestamp
• Allows informed approval decision

​

Step-by-Step Process

​

On the New Device

1. Go to login page
2. Enter your handle
3. Click “Confirm on a trusted device”
4. Screen shows “Waiting for approval…”
5. Device subscribes to WebSocket updates
6. Falls back to polling if WebSocket unavailable

​

On a Trusted Device

1. Receive real-time notification (red badge on “Login Requests”)
2. Navigate to Dashboard → Login Requests
3. Review device information:
   • Device icon (computer/phone/tablet)
   • Browser and OS
   • IP address
   • Time of request
4. Click “Approve” or “Deny”

​

After Approval

• New device receives encrypted master key
• Master key decrypted with ephemeral shared secret
• Session created automatically
• Both devices now have full access
• Login request deleted from database

​

Denial and Expiration

• New device shows “Request denied” immediately
• Option to try another method
• Request deleted from database

• Status changes to “expired”
• User must start a new login attempt
• Request remains in database until cleanup

​

WebSocket vs Polling

• Instant notifications on both devices
• Lower latency for approval flow
• Connection-aware status

• 2-second intervals via HTTP GET
• Works when WebSocket blocked/unavailable
• Reliable but higher latency

​

Recovery Method Comparison

​

Choosing the Right Method

​

For Daily Use

• Fastest and most convenient
• Biometric/PIN protected
• Syncs across your devices (via iCloud Keychain, Google Password Manager, etc.)

​

For Account Recovery

• All passkeys are lost/inaccessible
• Setting up from completely new environment
• Device approval not available (no active sessions)

​

For Adding New Devices

• You have another device with active session
• Want to review device info before approving
• Prefer not to retrieve stored trust codes

​

Recovery Planning

​

Before You Need Recovery

1. Register multiple passkeys on different devices
2. Save trust codes in secure offline storage
3. Keep one active session on a device you control
4. Test recovery flow at least once to verify it works

​

Creating a Recovery Kit

Ave Recovery Information
------------------------
Handle: your_handle
Primary Email: [email protected]

Trust Code 1: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
Trust Code 2: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

Passkeys Registered:
- Device 1 name and location
- Device 2 name and location

Last Updated: YYYY-MM-DD

​

Testing Your Recovery

1. Test passkey login - Log out and back in using biometric
2. Test trust code recovery - Use a trust code to log in from new browser
3. Test device approval - Request approval from incognito window
4. Verify master key access - Confirm you can decrypt existing data

​

Troubleshooting

​

Cannot Access Any Recovery Method

1. Check if passkeys synced to another device (iCloud, Google account)
2. Search for trust codes in password manager, notes, or physical storage
3. Check email for account creation confirmation (may include recovery info)
4. Contact Ave support with identity verification

​

Trust Code Not Working

• Invalid code errors
• No codes found errors
• Master key decryption failures

​

Device Approval Stuck

1. Refresh the trusted device
2. Navigate manually to Dashboard → Login Requests
3. Check browser console for WebSocket errors
4. Try polling fallback (wait 5-10 seconds)
5. Request may have expired - try again

​

Passkey Not Recognized

1. Ensure you’re on correct domain/localhost port
2. Check if passkey synced to this device
3. Verify browser supports WebAuthn (Chrome, Edge, Safari, Firefox)
4. Try different browser or device
5. Use trust code recovery as fallback

​

Security Considerations

​

Activity Logging

{
  "action": "login",
  "details": { "method": "trust_code" | "passkey" | "device_approval" },
  "severity": "info" | "warning",
  "ipAddress": "...",
  "deviceId": "..."
}

​

Failed Attempt Monitoring

{
  "action": "trust_code_failed" | "key_recovery_failed",
  "details": { "reason": "invalid_code" },
  "severity": "warning"
}

​

Rate Limiting Recommendations

• Limit trust code attempts per IP/handle
• Exponential backoff for failed passkey verifications
• CAPTCHA after multiple failed attempts

​

Related Topics

• Trust Codes - Detailed trust code documentation
• Session Management - Session tokens and cookies
• Best Practices - Security recommendations