proxy-detection/README.md

# Proxy Detection API

A simple Bun and Fastify API that extracts IP addresses from HTTP request headers to detect potential proxy leaks.

## Features

- **Built-in IP Detection**: Fastify's `trustProxy` automatically parses proxy headers
- **Full IP Chain**: Get the complete proxy chain, not just the client IP
- **Custom Header Analysis**: Extracts IPs from 17+ different proxy headers
- **No External Dependencies**: Works entirely by analyzing request headers
- **Fast Performance**: Fastify is one of the fastest Node.js frameworks

## Installation

```bash
bun install
```

## Usage

### Development
```bash
bun run dev
```

### Production
```bash
bun run start
```

## Docker Deployment

### Quick Start with Docker
```bash
# Build the image
npm run docker:build

# Run the container
npm run docker:run
```

### Using Docker Compose
```bash
# Development
npm run docker:dev

# Production (with nginx reverse proxy)
npm run docker:prod
```

### Manual Docker Commands
```bash
# Build
docker build -t proxy-detection-api .

# Run
docker run -p 9999:9999 proxy-detection-api

# Run with environment variables
docker run -p 9999:9999 -e NODE_ENV=production proxy-detection-api
```

## GitLab CI/CD

This project includes a complete GitLab CI/CD pipeline that:

1. **Tests** - Runs tests and TypeScript compilation
2. **Builds** - Creates Docker images and pushes to GitLab Container Registry
3. **Deploys** - Deploys to staging/production environments

### Pipeline Stages:
- `test` - Runs on MRs and main branch
- `build` - Builds Docker images on main/develop/tags
- `deploy_staging` - Manual deployment to staging (develop branch)
- `deploy_production` - Manual deployment to production (main branch/tags)

### Required GitLab Variables:
- `CI_REGISTRY_USER` - GitLab registry username (auto-provided)
- `CI_REGISTRY_PASSWORD` - GitLab registry password (auto-provided)
- Add your deployment-specific variables in GitLab CI/CD settings

The API will be available at `http://localhost:9999`

### Endpoints

#### `GET /`
Returns API information and available endpoints.

#### `GET /detect`
Extracts all IP addresses found in request headers with full proxy chain detection.

**Response:**
```json
{
  "success": true,
  "clientIP": "203.0.113.45",          // Fastify's auto-detected client IP
  "ipChain": ["203.0.113.45", "192.168.1.100"], // Complete proxy chain
  "foundIPs": ["192.168.1.100", "203.0.113.45"], // IPs found by custom parser
  "totalFound": 2,
  "headersSources": {
    "x-forwarded-for": ["192.168.1.100", "203.0.113.45"],
    "x-real-ip": ["203.0.113.45"]
  },
  "allHeaders": { ... },
  "timestamp": 1672531200000
}
```

## What's New with Fastify

### Trust Proxy Support
Fastify automatically handles proxy headers when `trustProxy: true` is enabled:
- Parses `X-Forwarded-For` header automatically
- Provides `request.ip` (client IP) and `request.ips` (full chain)
- More secure than manual header parsing

### Built-in IP Chain Detection
```javascript
// Fastify automatically provides:
request.ip    // "203.0.113.45" (real client)
request.ips   // ["203.0.113.45", "10.0.0.1", "192.168.1.100"] (full chain)
```

## Installation

```bash
# Install dependencies
bun install
```

## Usage

```bash
# Development (with auto-reload)
bun run dev

# Production
bun run start
```

## API Endpoints

### `GET /`
Returns API information and available endpoints.

### `GET /detect`
Performs a comprehensive proxy detection check:
```json
{
  "success": true,
  "data": {
    "yourIP": "1.2.3.4",
    "externalIPs": [
      {
        "ip": "1.2.3.4",
        "source": "ipify",
        "timestamp": 1234567890
      }
    ],
    "isProxyWorking": true,
    "leakedIPs": [],
    "timestamp": 1234567890
  },
  "message": "Proxy is working correctly"
}
```

### `GET /quick`
Quick IP check using a single service:
```json
{
  "ip": "1.2.3.4",
  "timestamp": 1234567890
}
```

### `GET /headers`
Shows request headers and client IP information:
```json
{
  "clientIP": "1.2.3.4",
  "headers": {
    "x-forwarded-for": "1.2.3.4",
    "user-agent": "Mozilla/5.0..."
  }
}
```

## How It Works

1. **Multiple IP Sources**: Queries several IP detection services (ipify, httpbin, ipapi, jsonip)
2. **Comparison**: Compares results to detect inconsistencies
3. **Leak Detection**: If different services return different IPs, it indicates a potential proxy leak
4. **Analysis**: Determines if your proxy is working correctly

## Use Cases

- Test if your VPN/proxy is working
- Detect DNS leaks
- Monitor IP consistency across services
- Verify anonymity tools

## Example Response (Proxy Working)
```json
{
  "yourIP": "192.168.1.100",
  "isProxyWorking": true,
  "leakedIPs": [],
  "message": "Proxy is working correctly"
}
```

## Example Response (IP Leak Detected)
```json
{
  "yourIP": "192.168.1.100",
  "isProxyWorking": false,
  "leakedIPs": ["203.0.113.5"],
  "message": "Potential IP leak detected: 203.0.113.5"
}
```