## ADR: IP Management Access Control System

Date: 2025-10-28
Status: proposed
Context: RateLoader HTTP server needs access control to restrict or allow specific IP addresses from connecting to the service. Currently, all IP addresses can access the server without any restrictions, which poses potential security risks.

Decision: Implement an IP Management system with per-IP address access control, global access modes, and a GUI interface for management. The system will track all connecting IPs with metadata and provide both automatic and manual control options.

### Key Components

1. **IP Manager Module** (`core/ip_manager.py`): Central component for IP tracking and access control
2. **JSON Storage** (`ip_access.json`): Persistent storage for IP data and access rules
3. **HTTP Server Integration**: Request filtering and IP tracking in the request handler
4. **GUI Tab**: User interface for viewing and managing IP access rules

### Access Control Logic

```
if global_access == "restricted":
    # Whitelist mode: only explicitly allowed IPs can access
    return ip_status == "allowed"
else:  # global_access == "allowed"
    # Blacklist mode: all IPs can access unless explicitly restricted
    return ip_status != "restricted"
```

### Data Structure

Each IP address tracks:

- Status: "allowed" or "restricted"
- First seen timestamp
- Last seen timestamp
- Request count
- Last request type (GET/POST)

Consequences:

**Positive:**

- Provides granular control over server access
- Maintains audit trail of all connections
- Intuitive GUI management interface
- Automatic IP discovery reduces manual configuration
- Global switch allows quick access mode changes
- Persistent storage survives application restarts

**Negative:**

- Additional file I/O operations for each request
- Increased memory usage for IP tracking
- More complex request processing logic
- Potential performance impact with high request volumes
- Additional GUI complexity

**Mitigations:**

- Implement IP count limits with LRU eviction
- Batch file operations to reduce I/O overhead
- Use efficient data structures for IP lookups
- Provide configuration options for tracking limits

Alternatives considered:

1. **Configuration file only**: Store IPs in settings.ini

   - Rejected: Would clutter main configuration file, limited structure

2. **Database storage**: Use SQLite for IP tracking

   - Rejected: Overkill for this use case, adds dependency

3. **In-memory only**: No persistent storage

   - Rejected: Would lose all data on restart, no audit trail

4. **External firewall**: Use OS-level firewall rules
   - Rejected: Requires admin privileges, not portable, no GUI integration

Links:

- Design document: [docs/ip_management_design.md](../docs/ip_management_design.md)
- Implementation: [core/ip_manager.py](../core/ip_manager.py)
- GUI integration: [gui/app.py](../gui/app.py)
- HTTP server changes: [core/http_server.py](../core/http_server.py)
