Multi-Account Support — Design Proposal

[saknarajapakshe]

TL;DR

Quicksilver currently supports exactly one email account per device. This proposal adds support for linking multiple accounts and switching between them, in a way that doesn't block a later move to OAuth.

• Split account profile (LinkedAccount) from account session (AccountSession) as separate types — they have different lifecycles.
• Use two contexts instead of one: AuthContext (auth mechanics, password today, OAuth-ready later) + AccountContext (linked accounts, sessions, switching).
• If an account is already open in another tab, switching opens/focuses that tab (Gmail-style) via named window.open target — no custom cross-tab protocol.
• Every linked account stays realtime-synced, not just the one on screen — cheap at current ~2.5 accounts/user average and makes switching simpler.
• No backend changes required for v1. The session store already supports multiple concurrent sessions.
• OAuth implementation is out of scope for this proposal — only the extension seam is designed now.

Jump to Section 11 – Decisions for the settled calls, or Feedback wanted for open questions.

---

Contents

1. Goal
2. Current State
3. Design Principles
4. Data Model Changes
5. Two Contexts: AuthContext + AccountContext
6. UI Plan
7. Realtime Sync Across Multiple Accounts
8. Backend / API
9. Future-Proofing for OAuth
10. Phased Implementation Plan
11. Decisions
12. Feedback wanted

Note

The links above use explicit anchors rather than GitHub auto-generated heading slugs, since auto-slug anchors aren’t always reliably clickable inside Discussion posts.

---

1. Goal

Today Quicksilver supports exactly one email account per device/browser.
A user registers with one email + app password (or IMAP/SMTP app-specific credential), and the app hard-blocks login with a different address on the same device (AuthContext.tsx, login() throws "wrong_email").

We want to:

1. Let a user add multiple email accounts to the client.
2. Let them switch between accounts from the UI (Gmail-style account switcher).
3. Ensure server requests always use the currently active account’s credentials/session.
4. Do this in a way that does not block future migration to OAuth (Google/Microsoft), so this work isn’t redone.

This proposal covers UI + client-side account management only.
It documents backend implications for future OAuth cohesion, but backend OAuth implementation itself is out of scope for now.

Non-goals

• Unified inbox across accounts.
• Realtime sync beyond each account’s default/inbox mailbox.
• Cross-account search.
• Shared drafts or compose spanning accounts.
• OAuth implementation itself (only extension seam design in this proposal).

---

2. Current State (what exists today)

A large part of the groundwork already exists.

Layer	Current behavior	File
Auth state	Single currentUser, single JWT ref, single MailProfile in localStorage["quicksilver_profile"]	src/nonview/core/AuthContext.tsx
Login guard	Rejects sign-in with different email than registered on device	AuthContext.tsx (login(), ~line 186)
Server session	JWT points to server-side session (session_id); store is map[sessionID]*Session, not user-keyed	server/internal/session/store.go, server/internal/auth/jwt.go
API client	Single APIClient in AuthProvider, token via getToken closure	src/nonview/api/client.ts
Local cache (IndexedDB)	Already namespaced by account on rows; includes clearAccount(account)	src/nonview/cache/db.ts
Data model	Thread/ThreadMessage have no accountId; scoping happens at cache layer	src/nonview/core/DataContext.tsx
UI	Sidebar has static profile row → /profile; no dropdown/menu pattern exists yet	src/view/moles/Sidebar.tsx, src/view/moles/Header.tsx

Important

Cache is already multi-account-friendly. The real gap is:

1. AuthContext (single-account assumptions),
2. API client token model (single implicit token),
3. UI (no account switcher).

---

3. Design Principles

• No over-engineering, no under-engineering. Requirement is unlimited linked accounts + independent session lifecycles + multiple tabs on different accounts.
• Additive, not rewrite. Two contexts instead of forcing all concerns into AuthContext.
• One session per linked account. Switching just points derived APIClient at the selected account’s token.
• Credential-method agnostic. Include authMethod now so OAuth later is additive.

---

4. Data Model Changes

4.1 Replace single MailProfile with account list; split Account vs Session

LinkedAccount (identity + server endpoints) and AccountSession (auth session token) are separate because they have different lifecycles.

TypeScript shapes

type AuthMethod = "password" | "oauth"; // "oauth" unused until Phase 5

interface LinkedAccount {
  id: string; // stable id, e.g., lowercased email
  email: string;
  name: string;
  emailServiceProvider?: string;
  imapHost: string;
  imapPort: number;
  imapSecure: boolean;
  smtpHost: string;
  smtpPort: number;
  smtpSecure: boolean;
  authMethod: AuthMethod; // "password" for all accounts today
}

interface AccountSession {
  accountId: string; // FK -> LinkedAccount.id
  token: string;
  expiresAt: string; // ISO 8601 from LoginResponse.expires_at
}

Stored as:

• localStorage["quicksilver_accounts"] → LinkedAccount[]
• localStorage["quicksilver_sessions"] → AccountSession[]
• per-tab active account id (see Section 6.1)

Passwords are never stored.

Warning

quicksilver_sessions increases XSS blast radius (multiple account tokens in one storage boundary).
This is an amplification of existing localStorage trust assumptions, not a new trust model.
Mitigation remains strict CSP + sanitized HTML paths (e.g., DOMPurify).

4.2 Migration for existing users

Migration steps

On first load after update, if old keys exist and new account list doesn’t:

1. Convert old quicksilver_profile to one-item LinkedAccount[].
2. Convert old quicksilver_jwt to one-item AccountSession[] (required).
3. Seed sessionStorage["quicksilver_active_account"] with migrated account id.
4. Remove old keys (quicksilver_profile, quicksilver_jwt).

4.3 Domain data (Thread, cache)

No domain type changes needed. Cache already scopes by account key.

---

5. Two Contexts: AuthContext + AccountContext

AuthContext: how credentials become valid sessions.
AccountContext: which accounts are linked/active and how switching works.

5.1 AuthContext — authentication mechanics

Interface + client handling

interface AuthContextValue {
  login: (req: LoginRequest) => Promise<LoginResponse>;
  register: (data: RegistrationData) => Promise<LoginResponse>;
  logout: (session: AccountSession) => Promise<void>;
  // Future:
  // loginWithOAuth: (provider: "google" | "microsoft") => Promise<LoginResponse>;
}

Notes:

• Do not expose apiClient from AuthContext.
• Keep:
  • unauthenticated client for login/register
  • disposable session-scoped client for logout/reauthenticate

5.2 AccountContext — linked accounts, sessions, switching

Interface + behavior

interface AccountContextValue {
  accounts: LinkedAccount[];
  sessions: AccountSession[];
  activeAccount: LinkedAccount | null;
  activeSession: AccountSession | null;
  isAuthenticated: boolean; // activeSession exists and is unexpired
  loading: boolean;
  apiClient: APIClient; // derived from activeSession token

  addAccount: (data: RegistrationData) => Promise<LinkedAccount>;
  switchAccount: (id: string) => void;
  removeAccount: (id: string) => Promise<void>;
  reauthenticate: (id: string, password: string) => Promise<void>;
  logoutAll: () => Promise<void>;
}

Behavior highlights:

• addAccount/reauthenticate call AuthContext then persist session.
• On 401, invalidate only that account’s session.
• switchAccount updates active pointer; data hydrates from IndexedDB + background refresh.
• removeAccount logs out session, clears cache, removes account/session entries.

5.3 Account lifecycle

• Persisted (global): Linked / Authenticated / Expired / Removed
• Per-tab (ephemeral): currently active account in this tab

State diagrams

Persisted lifecycle:

addAccount()/register
        │
        ▼
   ┌───────────┐
   │  Linked   │ (no session)
   └─────┬─────┘
         │ reauthenticate()
         ▼
   ┌───────────┐
   │Authenticated│ (has session)
   └─────┬─────┘
         ├── 401/onUnauthorized -> session dropped (account remains Linked)
         ├── expiresAt passes -> Expired
         ▼
   ┌───────────┐
   │  Expired  │
   └─────┬─────┘
         ├── reauthenticate() -> Authenticated
         └── removeAccount() -> Removed

Per-tab overlay:

switchAccount(id) -> this tab active = id
switchAccount(otherId) -> this tab active = otherId
(no account lifecycle transition required)

---

6. UI Plan

6.1 Account switcher component

Create src/view/moles/AccountSwitcher.tsx with MUI Menu/MenuItem.
Anchor to existing profile row in Sidebar.tsx (desktop) and profile avatar in Header.tsx (mobile).

Menu includes:

• Linked account list (avatar/initials + name + email + active highlight)
• Switch in current tab if target account has no existing tab
• Open/focus existing tab if target account already open
• “Add another account” (existing login/registration in add mode)
• Inline “Manage accounts” actions (remove row + sign out all)

Multi-tab model + switch sequence

Use named window target:

window.open(url, `quicksilver-${accountId}`);

Same target name reuses/focuses existing tab/window for that account.

[!CAUTION]
window.open must run synchronously in direct click handler context to avoid popup blocking.

Storage split:

• localStorage["quicksilver_accounts"] → shared profiles
• localStorage["quicksilver_sessions"] → shared sessions/tokens
• sessionStorage["quicksilver_active_account"] (or ?account=id) → tab-local active account

switchAccount(id) sequence:

1) Persist active account id (tab-local)
2) Cancel in-flight foreground fetch for old account view
3) Reset DataContext in-memory view state
4) Hydrate new account from IndexedDB (instant)
5) Start background delta sync

6.2 Reuse Login/Registration for “Add account”

Use ?mode=add so flow calls addAccount() instead of replacing current account session context.

6.3 Per-account visual identity (optional)

Nice-to-have only (distinct color/avatar per account).

---

7. Realtime Sync (SSE / IMAP IDLE) Across Multiple Accounts

Decision: every authenticated linked account stays live, even when not currently displayed.

At ~2.5 accounts/user and 5,000 concurrent users:

• active-only model: ~5,000 connections
• always-on-per-account: ~12,500 connections

Tradeoff: ~2.5× backend steady-state load for simpler switching + live unread badges across all accounts.

Design impact

• Realtime broadens from one active-account stream to one stream per authenticated session.
• switchAccount() requires no reconnect/teardown choreography.
• Backend change required: none.
• Scope remains default/inbox mailbox only (not all folders).

Revisit if account/user average or provider connection caps become problematic.

---

8. Backend / API — now vs later

Needed now: none.

Current backend session architecture already supports concurrent sessions.
Frontend only needs multi-session storage + active routing.

Note

Session store is in-memory; restart invalidates all sessions (already true today).
Impact is larger per user once multiple accounts are linked.

---

9. Future-Proofing for OAuth (not implementing yet)

• LinkedAccount.authMethod is the extension seam.
• “Add account” UI can later include Google/Microsoft without structural redesign.

Future backend work for OAuth

• /api/v1/auth/oauth/* endpoints
• session sealing extensions for OAuth access/refresh tokens
• XOAUTH2 support in IMAP/SMTP client

---

10. Phased Implementation Plan

Phase 1 — Data & context layer

• Add LinkedAccount[] + AccountSession[] storage and migration.
• Split AuthContext and AccountContext.
• Derive API token from active session.
• Add tab-local active account pointer.
• Keep single-account UX unchanged.

Phase 2 — Switcher UI + always-on per-account realtime

• Build AccountSwitcher, wire into Sidebar/Header.
• Add account mode in login/registration.
• Implement open/focus behavior for already-open account.
• Expand realtime to one subscription per session.
• QA multi-account, multi-tab, and non-displayed unread updates.

Phase 3 — Lifecycle polish

• Per-account expiry/re-auth prompts.
• Remove-account flow + cache cleanup.
• Implement sign-out-all.
• Handle edge cases (active removal, last account, duplicate email).

Phase 4 — Optional niceties

• Per-account unread badge polish.
• Optional keyboard quick-switch.
• No unified all-inboxes view.

Phase 5 — OAuth (separate initiative)

• OAuth backend routes + sealing changes.
• XOAUTH2 support.
• Add OAuth sign-in entry points in existing account-add seam.

---

11. Decisions

1. No cap on linked accounts.
2. Adding a new account switches to it immediately; switching to account already open elsewhere focuses that tab/window.
3. No unified all-accounts inbox in v1.
4. Manage accounts remains inline in switcher for v1.
5. Keep AuthContext and AccountContext separate; keep LinkedAccount and AccountSession separate.
6. Keep all linked authenticated accounts live for realtime sync; revisit only if scale/capacity data changes materially.

---

Feedback wanted

• Any objection to two-context split vs one combined context?
• Is always-on realtime sync acceptable at current account/user distribution, or should we add cap/toggle controls?
• Naming feedback: LinkedAccount, AccountSession, AccountContext?
• Any “non-goal” that should actually move into v1 scope?

[Aravinda-HWK]

@saknarajapakshe, What do you mean by

A unified inbox merging threads across accounts

In the non-goal section? Can you elaborate a bit?
.

[saknarajapakshe]

@saknarajapakshe, What do you mean by

A unified inbox merging threads across accounts

In the non-goal section? Can you elaborate a bit? .

It means combining the inbox threads from all the linked accounts into one single merged list, instead of switching between separate inboxes per account.

[Aravinda-HWK]

We have removed the concept of inbox, send, and draft folder structure.
Also, this is not a requirement for the system. It can be in the non-goal section. Currently, it is exactly in the non-goal section. ✅

[Aravinda-HWK]

Any objection to two-context split vs one combined context?

• Two contexts make the responsibilities much clearer. Therefore, keep them in separate context.

Is always-on realtime sync acceptable at current account/user distribution, or should we add cap/toggle controls?

• If average accounts per user is 2.5, I would say sync for all opened(not all authenticated) accounts is fine.

Naming feedback: LinkedAccount, AccountSession, AccountContext?

• No problem at all.

Any “non-goal” that should actually move into v1 scope?

• No, they are out of scope for this implementation.

@saknarajapakshe, please take this feedback and open issues, and you can start implementing this.