Skip to content

MULTI_ACCOUNT_SUMMARY.md

Latest commit

 

History

History
156 lines (125 loc) · 4.91 KB

MULTI_ACCOUNT_SUMMARY.md

File metadata and controls

156 lines (125 loc) · 4.91 KB

Multi-Account Implementation Summary

What Was Added

A complete Google-style multi-account system has been implemented for the application. This allows users to:

  • 🔄 Add and switch between multiple accounts without logging out
  • 🔐 Soft logout - sign out the session while keeping the account saved
  • 🗑️ Hard logout - completely remove an account from the device
  • 📝 Auto-fill - most recent account email automatically filled on login

Key Files Created

Core Logic

  • lib/multi-account.ts (165 lines)

    • Central module for all multi-account operations
    • Functions: addAccountToList, switchAccount, softLogout, hardLogout, etc.
    • Stores accounts in localStorage with refresh tokens

  • lib/use-multi-account.ts (110 lines)

    • React hook for easy component access to multi-account functions
    • Manages cross-tab sync via BroadcastChannel

UI Components

  • app/components/AccountSwitcher.tsx (150 lines)

    • Displayed on login page
    • Shows stored accounts for quick access
    • Click to switch, X button to remove

  • app/components/AccountsManager.tsx (170 lines)

    • Displayed in Settings → Account tab
    • Shows other logged-in accounts
    • Switch or remove functionality

  • app/components/LogoutDialog.tsx (120 lines)

    • Modal dialog for logout options
    • Soft Logout: Clear session, keep account
    • Hard Logout: Remove account completely

Documentation

  • MULTI_ACCOUNT_IMPLEMENTATION.md (300+ lines)
    • Complete technical documentation
    • Architecture, usage, security considerations
    • API reference and troubleshooting

Key Files Modified

Authentication Entry Points

  • app/login/page.tsx
    • Added addAccountToList() call after OAuth login
    • Added addAccountToList() call after Passkey login/registration
    • Added addAccountToList() call after Wallet login
    • Integrated AccountSwitcher component on login page
    • Auto-fill email from most recent account

Settings Page

  • app/settings/page.tsx
    • Integrated LogoutDialog for soft/hard logout options
    • Integrated AccountsManager to show other accounts
    • Count other accounts for UI awareness
    • Handle logout flow with multi-account awareness

How It Works (User Flow)

Adding an Account

  1. User logs in with email/OAuth/passkey/wallet
  2. Session created successfully
  3. addAccountToList() automatically stores refresh token
  4. Account appears in "Your Accounts" on login page next time

Switching Accounts

  1. User goes to login page or Settings
  2. Clicks on a stored account
  3. System kills current session
  4. System creates new session using stored refresh token
  5. All tabs/windows reload to reflect new user
  6. User sees new account's dashboard

Soft Logout

  1. User in Settings → Sign Out → Soft Logout
  2. Session cleared (true logout)
  3. Account remains stored in localStorage
  4. On login page, email auto-fills
  5. No credentials needed to log back in

Hard Logout

  1. User in Settings → Sign Out → Hard Logout
  2. Session cleared AND account removed from storage
  3. User returned to login page
  4. Account no longer in stored list
  5. Must log in manually with credentials

Data Storage

Accounts stored in localStorage with format:

{
  "id_multi_accounts": {
    "userId123": {
      "userId": "userId123",
      "email": "user@example.com",
      "name": "User Name",
      "refreshToken": "session_secret",
      "addedAt": 1697827200000
    }
  },
  "id_primary_account": "userId123"
}

Security Notes

⚠️ Refresh tokens are stored in localStorage, which is XSS-vulnerable

  • This is an intentional trade-off for convenience
  • Tokens are refresh tokens (not access tokens)
  • Users can hard logout to clear all tokens
  • Recommend using CSP headers and regular security audits

No Breaking Changes

✅ All existing functionality preserved:

  • OAuth (Google, GitHub)
  • Passkeys (registration & authentication)
  • Wallet authentication
  • Settings and security features
  • Passkey management
  • Everything else works exactly as before

Testing Checklist

Before deploying, test:

  • Log in with multiple accounts
  • Switch between accounts
  • Soft logout and login again
  • Hard logout verification
  • Cross-tab sync (open 2 windows, switch in one)
  • OAuth from multiple providers
  • Passkey login from multiple accounts
  • Settings page shows accounts correctly
  • Account switcher appears on login page

Browser Requirements

  • localStorage support (all modern browsers)
  • BroadcastChannel API (for cross-tab sync, optional - has fallback)

Next Steps

The implementation is complete and ready to use. No additional configuration needed. Users can start using multi-account features immediately after login.

Optional enhancements for future:

  • Device naming (e.g., "My Laptop", "My Phone")
  • Login location/time display
  • "Logout all devices" button
  • Server-side session tracking
  • Suspicious activity alerts