# GEMINI.md

## Project Overview

This project is a **VPN Access Server**, written in Python, designed to extend an OpenVPN server with custom authentication and session management features. It uses a MySQL database to store user information, authorized MAC addresses, and session data.

The core functionality is to:
1.  **Validate MAC Addresses**: Ensure only devices with authorized MAC addresses can connect to the VPN.
2.  **Enforce Session Time**: Manage and enforce session duration policies on a per-user basis.

The architecture is based on OpenVPN's `client-connect` and `client-disconnect` hooks, which execute Python scripts to perform the validation logic.

**Technologies:**
*   **Language:** Python 3
*   **Database:** MySQL
*   **VPN:** OpenVPN (as the execution environment)
*   **Dependencies:** `mysql-connector-python`, `pytest`

## Building and Running

The project is managed via a central command-line interface in `main.py`.

### Initial Setup

1.  **Install Dependencies:**
    ```bash
    uv pip install -r requirements.txt
    ```
    *(Note: Based on `pyproject.toml`, you might use `uv pip install .` or `uv pip install -e .` for editable mode)*

2.  **Configure Environment:**
    Create a `.env` file based on `.env.example` and provide the necessary database credentials:
    ```bash
    cp .env.example .env
    # Edit .env with your DB settings
    ```

3.  **Initialize the Database:**
    This script will create the necessary tables (`employees`, `mac_addresses`, `sessions`) in the database.
    ```bash
    python main.py init-db
    ```

### Running the Application

The main application logic is triggered by OpenVPN. However, you can run the individual components for testing or health checks.

*   **Run a Health Check:**
    Verifies the configuration and database connection.
    ```bash
    python main.py health-check
    ```

*   **Show Status:**
    Displays the current configuration.
    ```bash
    python main.py status
    ```

*   **Run Authentication/Session Logic (Manual Simulation):**
    These commands are intended to be called by OpenVPN but can be run manually if the required environment variables are set.
    ```bash
    # Simulate OpenVPN client-connect
    python main.py auth

    # Simulate OpenVPN client-disconnect
    python main.py session
    ```

### Running Tests

The project uses `pytest` for testing.

```bash
python main.py test
```
or
```bash
pytest
```

## Development Conventions

*   **Modular Architecture:** The code is structured into modules with clear responsibilities:
    *   `access/auth.py`: User authentication and MAC validation.
    *   `access/session.py`: Session management.
    *   `access/db.py`: Database interaction.
    *   `access/config.py`: Configuration loading.
    *   `access/utils.py`: Shared utility functions.
*   **Configuration:** Configuration is loaded from environment variables, following the 12-factor app methodology. A `.env` file is used for local development.
*   **Database Management:** Database connections are managed through a connection pool in `db.py` for efficiency. All SQL queries are centralized in this file.
*   **CLI:** A single entry point (`main.py`) provides a consistent way to interact with and manage the application.
*   **Testing:** Unit tests are located in the `tests/` directory and can be run with `pytest`.