# Study Report: Provider Detection Logic

This report analyzes the email provider detection system implemented in both **Direct Mode** and **Fileshare Mode**. The application uses a unified detection engine to ensure consistent behavior across both modes.

## Core Detection Engine (`email_provider_map.php`)

Both modes leverage a centralized PHP-based detection engine found in `email_provider_map.php`. The logic follows a tiered priority approach:

1.  **Direct Domain Mapping**: Matches the email domain against a static `$EMAIL_PROVIDER_MAP` (e.g., `gmail.com` -> `chameleon`, `outlook.com` -> `outlook`).
2.  **Subdomain Matching**: Checks if the domain is a subdomain of a known provider (e.g., `mail.bell.net` -> `Bell`).
3.  **MX Record Lookup**: For unknown domains, the system performs a DNS MX lookup:
    *   **Tier 0**: Matches specific Microsoft 365 patterns (`*-mail.protection.outlook.com`).
    *   **Tier 1**: Matches MX hostnames against known hostname patterns (e.g., `mx.zohomail.com`).
    *   **Tier 2**: Keyword-based matching (looking for "outlook", "zimbra", "zoho", etc., in the MX records).
    *   **Tier 3**: Active Port Identification – attempts a connection to port 2096 to detect cPanel webmail.
4.  **Fallback**: Defaults to `chameleon` if no specific provider is identified.

---

## Mode Comparison

### 1. Direct Mode
**Implemented in:** `direct_loader.php`
**Activation:** Controlled by `define('APP_MODE', 'direct')` in `config_mode.php`.

*   **Execution Flow**:
    1.  The server verifies the session/token (`vtoken`).
    2.  Checks for IP blacklisting and basic bot User-Agents.
    3.  Extracts the target email from the `ref` query parameter.
    4.  Calls the **Core Detection Engine** server-side.
    5.  Performs a server-side HTTP 302 redirect to the specific provider page (e.g., `providers/outlook.php?ref=...`).
*   **User Experience**: The user skips the "File Share" UI entirely and goes straight from the CAPTCHA/Entrance gate to the provider-specific login page.

### 2. Fileshare Mode (Default)
**Implemented in:** `index.php` + `js/email_provider_detector.js`
**Activation:** Controlled by `define('APP_MODE', 'fileshare')` in `config_mode.php`.

*   **Execution Flow**:
    1.  The user sees the "File Share" PDF viewer UI.
    2.  When the user clicks the "Verify Email" button:
        *   Client-side JS (`email_extractor.js`) pulls the email from the URL fragment or `ref` parameter.
        *   `email_provider_detector.js` makes an asynchronous `fetch` call to `detect_provider_api.php`.
        *   The API calls the **Core Detection Engine** and returns JSON (e.g., `{"status": "success", "provider": "owa"}`).
        *   The JS constructs the provider URL (e.g., `providers/owa.php?ref=...`).
        *   The JS dynamically loads this URL into an **iframe** (`#popup-iframe`) within a modal overlay.
*   **User Experience**: The user remains on the PDF viewer page, and the provider login appears as a "popup" (iframe) inside the fake browser container.

---

## Key Files Involved
*   `config_mode.php`: Defines the active mode.
*   `email_provider_map.php`: The "brain" of the detection system (PHP).
*   `detect_provider_api.php`: The bridge between JS and the PHP engine.
*   `js/email_provider_detector.js`: The client-side logic for Fileshare Mode.
*   `direct_loader.php`: The server-side logic for Direct Mode.
*   `index.php`: The main UI that hosts Fileshare Mode.
