# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a VPN Access Server project that extends OpenVPN functionality with custom MAC address validation and session time management. The system integrates with MySQL for data persistence and is designed for deployment on Ubuntu VPN gateways.

## Development Commands

This project uses `uv` as the package manager and `main.py` as the unified entry point:

**Package Management:**
- **Install dependencies**: `uv install`
- **Add test dependencies**: `uv add --group test pytest pytest-cov`
- **Activate virtual environment**: `source .venv/bin/activate`

**Console Script Commands (Recommended):**
- **Show help**: `uv run vpn-access-server --help`
- **Show status**: `uv run vpn-access-server status`
- **Run tests**: `uv run vpn-access-server test`
- **Health check**: `uv run vpn-access-server health-check`
- **Initialize database**: `uv run vpn-access-server init-db`
- **Seed test data**: `uv run vpn-access-server seed-data`

**Direct OpenVPN Integration:**
- **Authentication**: `uv run vpn-access-server auth` (called by OpenVPN)
- **Session management**: `uv run vpn-access-server session` (called by OpenVPN)

**Alternative Direct Python Commands:**
- **Main script**: `uv run python main.py [command]`
- **Direct script access**: `python access/auth.py` or `python access/session.py`

**Alternative Testing:**
- **Run pytest directly**: `uv run pytest tests/`
- **Run specific test**: `uv run pytest tests/test_utils.py`

## Architecture

The system follows a modular layered architecture with these key components:

### Core Components
- **access/**: Python scripts that integrate with OpenVPN hooks (`client-connect` and `client-disconnect`)
- **MySQL Database**: Stores users, MAC addresses, and session data
- **OpenVPN Server**: Calls Python scripts during connection events

### Module Structure
- `access/auth.py`: User authentication and MAC validation logic
- `access/session.py`: Session tracking and time enforcement
- `access/db.py`: MySQL connection and database queries
- `access/utils.py`: Shared utility functions
- `access/config.py`: Configuration management (DB credentials, constants)

### Database Schema
- `users`: User accounts with session limits
- `mac_addresses`: Allowed MAC addresses per user
- `sessions`: Connection session tracking with duration

## Integration Flow

1. OpenVPN receives connection attempt
2. Calls `client-connect` Python script with environment variables
3. Script validates user status, MAC address, and session limits via MySQL
4. Connection allowed/denied based on validation
5. On disconnect, `client-disconnect` script updates session duration

## Security Notes

- Uses parameterized SQL queries to prevent injection
- Database credentials should be secured via environment variables or config files
- All validation failures are logged for auditing
- Scripts run with minimal privileges in `/etc/openvpn/access/` on deployment
- Always use `uv run` command whenever you run a python file in a project or source