OAuth Authentication Helper

Relevant source files

The following files were used as context for generating this wiki page:

• oauth_auth.py
• config.py
• main.py
• locales/en.json
• check_user_authorized.py
• totally_reset_cursor.py

The OAuth Authentication Helper is a key module responsible for automating the user registration process for Cursor via Google and GitHub OAuth providers. It uses browser automation to navigate the authentication flow, retrieve the necessary session tokens, and handle account state, including automatic deletion and re-registration if usage limits are met.

This system is orchestrated by the OAuthHandler class, which leverages the DrissionPage library for browser control. It is designed to be robust across different operating systems (Windows, macOS, Linux) and supports multiple browser types. The user interface and messages are internationalized using a translator that pulls strings from JSON locale files.

Architecture

The core of the feature is the OAuthHandler class, which encapsulates all logic for browser setup, authentication, and account management.

Sources: oauth_auth.py:25-27

Core Components

Component	Description	File
OAuthHandler	The main class that manages the entire OAuth flow.	oauth_auth.py
DrissionPage.ChromiumPage	The browser automation library used to control the browser.	oauth_auth.py
CursorAuth	A class used to update the local Cursor authentication information after a successful OAuth flow.	oauth_auth.py
config.py	Provides configuration settings for the browser type, paths, and wait times.	config.py
Translator	Handles internationalization (i18n) for user-facing messages.	main.py

Class Diagram

The following diagram shows the structure of the OAuthHandler class and its primary methods.

Sources: oauth_auth.py:25-1082

Browser Setup and Management

Before initiating the OAuth flow, the helper must configure and launch a browser instance. This process is handled by the setup_browser method and involves several platform-specific steps.

Sources: oauth_auth.py:207-286

Browser Setup Flow

This flowchart outlines the sequence of operations performed during browser setup.

Sources: oauth_auth.py:207-286

Browser and Profile Discovery

The helper automatically detects the user data directory and executable path for the configured browser (chrome, brave, edge, etc.).

• _get_user_data_directory(): Determines the path to the browser's user data based on the OS. It defaults to Chrome if the configured browser's directory is not found.
• _get_browser_path(): Finds the browser's executable. It first checks the configuration file for a specific path, then searches common installation locations for the selected browser and falls back to Chrome if necessary.
• _select_profile(): Lists available browser profiles from the Local State file and prompts the user to select one. This allows the automation to use a browser profile where the user is already logged into Google or GitHub.

Sources: oauth_auth.py:73-195, oauth_auth.py:348-410, oauth_auth.py:412-519

Browser Process Management

To ensure a clean state, the _kill_browser_processes method terminates any running instances of the target browser before launching a new one. The processes to be killed are specific to the browser type and operating system.

Sources: oauth_auth.py:288-346

Authentication Flow

The authentication process is initiated by handle_google_auth or handle_github_auth. Both methods follow a similar sequence: set up the browser, navigate to the Cursor sign-up page, click the appropriate OAuth button, and wait for the authentication to complete.

Sources: oauth_auth.py:601-681, oauth_auth.py:821-893

Sequence Diagram for Google Authentication

This diagram illustrates the interactions between the user, the script, and external services during the Google OAuth flow.

Sources: oauth_auth.py:601-778

Waiting for Authentication (_wait_for_auth)

After the user interacts with the OAuth provider, the _wait_for_auth method polls the browser state to detect a successful login. It does this by repeatedly checking for the WorkosCursorSessionToken cookie. Once the token is found, it navigates to the Cursor settings page to retrieve the user's email and check their AI usage.

Sources: oauth_auth.py:683-819

Usage Limit and Account Deletion

A critical feature of the helper is its ability to handle accounts that have reached their usage limits. During the _wait_for_auth process, after a successful login, the script navigates to https://www.cursor.com/settings and scrapes the usage count.

If the usage limit (e.g., 50/50 for the free plan) is reached, the script automatically triggers the account deletion process and restarts the authentication flow.

Sources: oauth_auth.py:739-763, oauth_auth.py:1040-1082

Account Deletion Logic

The _delete_current_account method injects and executes JavaScript in the browser to send a POST request to the /api/dashboard/delete-account endpoint, effectively deleting the current account.

// Source: oauth_auth.py:1043-1065
function deleteAccount() {
    return new Promise((resolve, reject) => {
        fetch('https://www.cursor.com/api/dashboard/delete-account', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            credentials: 'include'
        })
        .then(response => {
            if (response.status === 200) {
                resolve('Account deleted successfully');
            } else {
                reject('Failed to delete account: ' + response.status);
            }
        })
        .catch(error => {
            reject('Error: ' + error);
        });
    });
}
return deleteAccount();

This JavaScript snippet is executed by the script to programmatically delete a Cursor account.

Usage Check and Deletion Flow

Sources: oauth_auth.py:739-763, oauth_auth.py:968-992

Internationalization (i18n)

The OAuthHandler uses a Translator instance to provide multi-language support for all user-facing messages. The text is fetched from JSON files located in the locales/ directory. Keys are referenced in a dot-notation format, such as oauth.google_start.

Sources: oauth_auth.py:26, locales/en.json:300-362, main.py:46-248

Example of an English translation key:

// Source: locales/en.json:332
"oauth": {
    "google_start": "Google start",
    "github_start": "Github start",
    "usage_count": "Usage count: {usage}",
    "account_has_reached_maximum_usage": "Account has reached maximum usage, {deleting}",
    "starting_new_authentication_process": "Starting new authentication process..."
}

Summary

The OAuth Authentication Helper is a sophisticated automation script that streamlines the creation of Cursor accounts. It manages the entire browser-based OAuth2 flow, handles OS and browser-specific configurations, and intelligently manages account lifecycle by checking usage limits and performing automated cleanup. This functionality is central to the project's goal of providing continuous access to Cursor's features.