Authentication and User Management

Relevant source files

Warp utilizes a sophisticated authentication system centered around a state machine that manages user transitions from anonymous states to authenticated cloud-synced accounts. The system integrates local credential storage with Firebase for identity management and a GraphQL API for user profile and preference synchronization.

Auth Manager State Machine

The core of the authentication system is the AuthManager, which maintains the current AuthState. This state machine ensures that the application responds correctly to login, logout, and credential expiration events.

Authentication States

The system transitions through several key states defined in the authentication logic:

  • Loading: Initial state while checking for stored credentials.
  • Unauthenticated: No user is logged in; the application may operate in a limited "logged-out" mode.
  • Authenticated: A user is successfully logged in with valid Firebase credentials and a Warp UID.
  • Authenticating: A transient state during the web handoff or SSO flow.

Implementation Details

The AuthManager is responsible for:

  1. Credential Persistence: Securely storing and retrieving refresh tokens from the platform's keychain/keystore.
  2. Token Refresh: Automatically handling Firebase ID token expiration by using refresh tokens.
  3. User Identity: Mapping Firebase identities to internal Warp User objects containing the UID.

Sources: app/src/auth/mod.rs1-100 app/src/auth/manager.rs1-150

Web Handoff and SSO Flow

Warp uses a "Web Handoff" pattern for authentication to support various SSO providers (Google, GitHub, etc.) without embedding complex OAuth logic directly in the terminal.

Flow Sequence

  1. Initiation: The user clicks "Login" in the Warp UI.
  2. Browser Redirect: Warp opens the system browser to a hosted authentication page.
  3. Authentication: The user completes SSO via Firebase on the web.
  4. Local Server: The Warp application starts a temporary local HTTP server (typically on a high-numbered port) to listen for the auth callback.
  5. Token Exchange: The web page redirects to the local server with the credentials.
  6. Completion: Warp receives the tokens, shuts down the local server, and updates the AuthManager state.

Error Handling

Login errors (e.g., network failures, cancelled flows, or invalid credentials) are handled by specific error variants that the UI uses to display actionable feedback to the user.

Sources: app/src/auth/handoff.rs1-80 app/src/auth/error.rs1-50

Integration Architecture

The authentication system bridges the local application with cloud services through two primary crates: firebase and graphql.

Firebase Integration (crates/firebase/)

This crate acts as a wrapper around Firebase Authentication services. It handles:

  • Communication with Firebase Auth REST APIs.
  • Validation of JWT tokens.
  • Management of anonymous user sessions before full account creation.

GraphQL API Integration (crates/graphql/)

Once authenticated, the AuthManager provides the necessary headers (Bearer tokens) to the GraphQL client. This allows the application to:

  • Fetch the user's profile and settings.
  • Link local anonymous IDs to a permanent user account.
  • Sync Warp Drive objects and preferences.

Code Entity Space Mapping

The following diagram illustrates how the logical authentication concepts map to specific code entities within the repository.

Authentication Entity Mapping

Code Entity Space

Natural Language Space

manages

starts

persists to

uses tokens from

User Identity

Login Flow

Credential Storage

Cloud Sync

AuthUser (app/src/auth/user.rs)

UserIdentifier (crates/warp_graphql_schema/src/user.rs)

AuthManager (app/src/auth/manager.rs)

WebHandoffServer (app/src/auth/handoff.rs)

KeychainCredentials (app/src/auth/credentials.rs)

WarpGraphqlClient (crates/graphql/src/client.rs)

FirebaseClient (crates/firebase/src/lib.rs)

Sources: app/src/auth/manager.rs20-60 crates/firebase/src/lib.rs1-40 crates/graphql/src/client.rs1-50

Data Flow: Authentication Lifecycle

The following sequence diagram details the data flow during a successful login operation, from the user interaction to the final state update.

Login Data Flow

"GraphQL API (crates/graphql/)""Firebase (crates/firebase/)""WebHandoff (app/src/auth/handoff.rs)""AuthManager (app/src/auth/)""User""GraphQL API (crates/graphql/)""Firebase (crates/firebase/)""WebHandoff (app/src/auth/handoff.rs)""AuthManager (app/src/auth/)""UserClick LoginStart Local ServerOpen Browser (SSO)Redirect with Auth CodePass CredentialsExchange Code for ID TokenReturn JWT & Refresh TokenFetch User Profile (me query)Return Warp UID & ProfilePersist Refresh Token to KeychainTransition to Authenticated State

Sources: app/src/auth/manager.rs100-200 app/src/auth/handoff.rs40-90 crates/graphql/src/client.rs60-120

Anonymous IDs and User UIDs

Warp distinguishes between an Anonymous ID and a User UID:

  • Anonymous ID: Generated on first launch and stored locally. Used for telemetry and basic persistence before the user creates an account.
  • User UID: A permanent, unique identifier assigned by the Warp backend upon account creation.

When a user logs in for the first time, the system performs an "Account Linking" operation where the local anonymous data is associated with the new permanent UID in the cloud database.

Sources: app/src/auth/user.rs10-40 crates/warp_graphql_schema/src/user.rs1-30

Developer Tooling and PR Requirements

When making changes to the authentication system or any core component, engineers must follow the repository's established testing and PR workflows.

Pre-PR Checklist

Before submitting changes to the auth system:

  1. Merge Master: Always merge the latest origin/master into the feature branch.
  2. Presubmit Checks: Run ./script/presubmit to ensure code formatting (cargo fmt), linting (cargo clippy), and all tests pass.
  3. Regression Testing: Any bug fixes in the auth flow must include a regression test that reproduces the failure before the fix.

Testing Infrastructure

Tests are managed via nextest. Integration tests, which are crucial for auth flows, are configured with specific overrides:

Sources: .config/nextest.toml:1-40