Lunexia VPN leverages Chrome's native proxy management APIs to provide seamless traffic routing without requiring system-level permissions or external dependencies. The architecture is designed to be lightweight, reliable, and transparent.

Data Flow

1. User selects a location and clicks Connect in the extension popup
2. Extension retrieves proxy configuration for the selected location from local storage
3. Configuration is applied via chrome.proxy.settings.set() API
4. Chrome immediately begins routing all browser traffic through the specified proxy server
5. If authentication is required, credentials are automatically provided from secure storage
6. Connection state is saved to local storage for persistence across sessions
7. Badge icon and popup UI update to reflect the active connection

3.1 Proxy Configuration Layer

At the core of Lunexia is the Chrome Proxy API (chrome.proxy.settings), which provides programmatic control over the browser's proxy configuration. This API allows the extension to:

• Configure proxy rules for different protocols (HTTP, HTTPS, SOCKS)
• Set bypass rules for specific domains or IP ranges
• Clear proxy settings to return to direct connection
• Read current proxy state for UI synchronization

The extension builds a proxy configuration object that specifies the server host, port, protocol, and authentication details. This configuration is then applied globally to all browser traffic, with the exception of any specified bypass rules.

{
  mode: "fixed_servers",
  rules: {
    singleProxy: {
      scheme: "http",
      host: "proxy.example.com",
      port: 8080
    },
    bypassList: ["localhost", "127.0.0.1"]
  }
}

3.2 Connection Lifecycle

The connection lifecycle in Lunexia follows a clear state machine pattern:

3.3 UI State & Feedback

Lunexia provides comprehensive visual feedback through multiple UI components:

• Extension Badge: Shows a colored dot and optional text (location code) to indicate connection status at a glance
• Popup Interface: Displays current location, connection state, loading spinner during transitions, and error messages if issues occur
• Notification System: Optional browser notifications for connection success, failure, or authentication issues

4.1 Authentication & Credential Storage

When using authenticated proxy servers, Lunexia stores your credentials locally using Chrome's storage APIs. These credentials are:

• Encrypted using browser-level encryption mechanisms
• Never transmitted to any server except your configured proxy
• Isolated to your browser profile and not accessible to other extensions or websites
• Deletable at any time through the extension settings

4.2 Threat Model

It's important to understand what Lunexia protects against and what it does not:

4.3 Permissions Explanation

Lunexia requests the following Chrome extension permissions:

• proxy: Required to configure and manage proxy settings
• storage: Needed to save your configuration, credentials, and connection state locally
• notifications (optional): Used to display connection status alerts

Lunexia does not request permissions for tabs, browsing history, cookies, or any other sensitive data access beyond what's strictly necessary for proxy functionality.

5.1 Adding a Proxy Server

While Lunexia comes with pre-configured proxy locations, you can also add your own custom proxy servers:

1. Open the Lunexia extension popup
2. Click on "Settings" or the gear icon
3. Navigate to "Custom Proxies" section
4. Click "Add Proxy"
5. Enter the proxy details (see format below)
6. Save the configuration
7. Your custom proxy will appear in the location list

Proxy Configuration Format

{
  "name": "My Custom Proxy",
  "location": "US",
  "protocol": "http",  // or "https", "socks4", "socks5"
  "host": "proxy.example.com",
  "port": 8080,
  "username": "myusername",  // optional
  "password": "mypassword"   // optional
}

5.2 Selecting Locations

To switch between proxy locations:

1. Click the Lunexia extension icon in your browser toolbar
2. In the popup, locate the "Location" dropdown menu
3. Browse the available proxy server locations
4. Click on your desired location
5. The extension will automatically apply the new proxy configuration
6. Wait for the connection indicator to turn green

Location switching is seamless and does not require disconnecting first. Your connection will briefly transition through a "switching" state before establishing the new route.

5.3 Troubleshooting Authentication Failures

If you encounter "Proxy authentication required" errors:

5.4 Reset / Disable Proxy

To completely disable proxy routing and return to direct connection:

1. Open the Lunexia extension popup
2. Click the large "Disconnect" button
3. All proxy configuration will be cleared immediately
4. Your browser will return to using your default network connection

To completely reset Lunexia (clear all settings, credentials, and custom proxies):

1. Open the extension popup and click "Settings"
2. Scroll to the bottom of the settings page
3. Click "Reset All Settings"
4. Confirm the reset action
5. The extension will clear all stored data and return to default configuration