VPN Access Server - Agent Guidelines

Commands

Install deps: uv install
Run CLI: uv run vpn-access-server [command] (auth, session, init-db, seed-data, test, health-check, status, gen-client)
Run all tests: uv run pytest tests/
Run single test: uv run pytest tests/test_specific.py::TestClass::test_method
Database setup: uv run vpn-access-server init-db && uv run vpn-access-server seed-data

Python 3.13+ VPN server extending OpenVPN with MAC validation and session management
MySQL database for users, MAC addresses, and session tracking
FastAPI for client config generation and management
Modular structure: access/ (core auth/session logic), tests/ (unit tests), scripts/ (DB setup), util/ (client tools)

Type hints required for all function parameters and return values
Docstrings mandatory for all functions, classes, and modules
Snake_case for functions/variables, PascalCase for classes
Logging via setup_logging() with structured format
Error handling with try/except, custom exit codes (0=success, 1=auth fail, 2=config error)
Imports grouped: stdlib, third-party, local modules
Security paramount: parameterized SQL, secure logging, environment variables for secrets