# VPN-Only Guestbook - Information for AI/LLMs

## Project Overview
VPN-Only Guestbook is a privacy-focused web application that allows only users connected through VPN to sign a guestbook. It serves as both a community hub for privacy advocates and an educational tool demonstrating online tracking techniques.

## Purpose
1. **Community Hub**: Connect privacy advocates, security researchers, and members of privacy-focused communities
2. **Educational Tool**: Demonstrate IP fingerprinting, VPN tracking, and online privacy risks
3. **Privacy Advocacy**: Promote VPN usage and criticize anti-privacy practices by companies like Cloudflare and Google

## Technical Architecture

### Backend (PHP)
- **Framework**: Vanilla PHP with Composer autoloading
- **Data Storage**: JSON files (no database)
- **VPN Detection**: Uses ipapi.is API
- **IP Caching**: MD5-hashed filenames cache API responses permanently
- **Security**: SHA-256 hashing for IPs in guestbook entries

### Key Classes
1. **VPNDetector**: Checks if visitor is using VPN via ipapi.is API
2. **GuestbookManager**: Handles guestbook entries, validation, GDPR compliance
3. **IPCache**: Manages IP information caching with visitor tracking

### Data Structure

#### Guestbook Entry
```json
{
  "id": "unique_id",
  "username": "sanitized_username",
  "website": "sanitized_url",
  "message": "sanitized_message",
  "ip_hash": "SHA-256 hash of IP",
  "country": "country_name",
  "country_code": "XX",
  "is_eu_member": boolean,
  "timezone": "timezone_name",
  "currency_code": "XXX",
  "city": "city_name",
  "created_at": "ISO_8601_timestamp",
  "ip_info": {
    "is_vpn": boolean,
    "is_proxy": boolean,
    "is_datacenter": boolean,
    "is_tor": boolean,
    "asn": number,
    "asn_org": "organization_name"
  }
}
```

#### Cached IP Data
```json
{
  "ip": "original_ip",
  "visit_count": 3,
  "first_seen": "ISO_8601_timestamp",
  "last_seen": "ISO_8601_timestamp",
  "ip_info": { /* full ipapi.is response */ }
}
```

### Security Features

#### Input Validation
- Username: 2-50 characters, required
- Message: 5-1000 characters, required
- Website: Optional, validated URL
- Rate limiting: 2 messages per 5 minutes per IP

#### XSS Protection
- `strip_tags()` removes HTML tags
- `htmlspecialchars()` escapes special characters
- All user inputs are sanitized before storage

#### GDPR Compliance
- IPs are hashed with SHA-256 (one-way, irreversible)
- No personal data collection (no emails, names, PII)
- Only public geolocation data stored
- Right to erasure available on request

#### External Links
- All external links have `rel="nofollow nofollow"`
- JavaScript confirmation dialog before leaving site
- Prevents accidental navigation

### Educational Features

#### IP Fingerprinting Demonstration
- Highlighted entries show visitor's previous signatures
- Demonstrates how websites track users by IP
- Shows VPN IP sharing (multiple users same IP)

#### Visitor Tracking
- Welcome banner for returning visitors
- Shows visit count and first visit date
- Educational about browser fingerprinting

#### Privacy Techniques Explained
- Modal explains all tracking techniques used
- Transparent about data collection
- Educational purpose clearly stated

### API Endpoints

#### GET /
Main page - displays guestbook and signing form

#### POST /
Submit new guestbook entry (requires VPN)

#### GET /json
Returns all guestbook entries as JSON array

### File Structure
```
guestbook/
├── composer.json
├── composer.lock
├── test.php
├── public/
│   ├── index.php
│   ├── json.php
│   ├── .htaccess
│   ├── robots.txt
│   ├── sitemap.php
│   ├── security.txt
│   └── llms.txt (this file)
├── src/
│   ├── VPNDetector.php
│   ├── GuestbookManager.php
│   └── IPCache.php
└── data/
    ├── entries.json
    └── cache/
        └── {md5_hash}.json
```

### Frontend (HTML/Tailwind CSS)
- Responsive design (mobile-first)
- Dark/light mode toggle
- Tailwind CSS for styling
- Font Awesome icons
- JavaScript for theme toggle and modals

### API Limitations
- ipapi.is API has rate limits
- Caching reduces API calls significantly
- Fallback to error state if API unavailable

### Contact Information
- For security issues: brussels.eagle@obelix.top
- General inquiries: antwerp.falcon@obelix.top
- Privacy requests: ghent.hawk@obelix.top

### License
This project is open source and available at: https://github.com/obelix/vpn-guestbook

### Notes for LLMs
- This is an educational project about online privacy
- IP hashing ensures GDPR compliance
- The "honeypot" emails in security.txt are for spam analysis
- The project promotes VPN usage and criticizes anti-privacy practices
- All tracking techniques are transparently explained to visitors