Skip to main content

Auth Architecture

LightningAddon uses a provider-agnostic auth system. Neither the UI nor the background worker import Firebase or Supabase directly — they consume a single ClientAuth interface.

How It Works​

createAuth() in @repo/auth lazy-loads the correct adapter based on VITE_BACKEND:

  • VITE_BACKEND=supabase — Supabase adapter (email/password via Supabase Auth)
  • VITE_BACKEND=firebase — Firebase adapter (email/password via Firebase Auth)
  • VITE_BACKEND=custom — Cookie adapter (reads session cookie from your domain, calls GET {apiBaseUrl}/auth/me)

All three adapters implement the same ClientAuth interface:

interface ClientAuth {
  signInWithEmail(email: string, password: string): Promise<ClientAuthUser>
  signUpWithEmail(email: string, password: string): Promise<ClientAuthUser>
  signOut(): Promise<void>
  resetPassword(email: string): Promise<void>
  getUser(): Promise<ClientAuthUser | null>
  onAuthStateChange(callback: (user: ClientAuthUser | null) => void): () => void
}

Backend Selection​

Set VITE_BACKEND to supabase, firebase, or custom. See Choosing Your Backend and Architecture: Backends for the feature comparison.

Legacy: When both Supabase and Firebase keys are present, VITE_AUTH_PROVIDER can disambiguate. Prefer VITE_BACKEND for new projects.

When VITE_BACKEND=custom, there is no extension login form. The adapter:

  1. Reads the session cookie from VITE_CUSTOM_COOKIE_DOMAIN via the Cookies API
  2. Requests cookies and host permissions if needed
  3. Calls GET {VITE_CUSTOM_API_URL}/auth/me with the cookie
  4. Returns { id, email } when the API validates the session

For full setup, endpoint contract, and manifest permissions, see Using with an Existing Backend.

Benefits​

  • Switch backends by changing one environment variable
  • No application code changes required
  • Custom backend lets you plug in any existing API and auth flow