# Système d'Autorisation basé sur IP

## Description

Ce middleware permet de restreindre l'accès aux APIs en fonction de l'adresse IP du client, au lieu d'utiliser un système d'autorisation basé sur les positions/rôles utilisateurs.

## Configuration

### Variables d'environnement (.env)

Ajoutez ces variables dans votre fichier `.env` :

```env
# Mode d'autorisation : 'whitelist' (liste blanche) ou 'blacklist' (liste noire)
IP_AUTH_MODE=whitelist

# Liste des IPs autorisées (mode whitelist) - séparées par des virgules
ALLOWED_IPS=127.0.0.1,::1,192.168.1.0/24,10.0.0.*

# Liste des IPs bloquées (mode blacklist) - séparées par des virgules
BLOCKED_IPS=123.456.789.0,45.67.89.0/24
```

### Configuration par défaut

Si aucune configuration n'est fournie, le système autorise par défaut :
- `127.0.0.1` (localhost IPv4)
- `::1` (localhost IPv6)
- `10.0.0.0/8` (réseau privé classe A)
- `172.16.0.0/12` (réseau privé classe B)
- `192.168.0.0/16` (réseau privé classe C)

## Utilisation

### Méthode 1 : Protection complète (recommandée)

Inclure au début de votre fichier API :

```php
<?php
require_once __DIR__ . '/middleware/ip-auth.php';

// Bloquer l'accès si l'IP n'est pas autorisée
requireIPAuthorization();

// Votre code API continue ici...
```

### Méthode 2 : Vérification conditionnelle

```php
<?php
require_once __DIR__ . '/middleware/ip-auth.php';

$ipAuth = new IPAuthorization();
$authResult = $ipAuth->isAuthorized();

if (!$authResult['authorized']) {
    // Loguer l'accès non autorisé
    error_log("Accès refusé depuis IP: " . $authResult['ip']);

    // Retourner une erreur personnalisée
    http_response_code(403);
    echo json_encode([
        'error' => 'Access denied',
        'message' => 'Votre adresse IP n\'est pas autorisée'
    ]);
    exit;
}

// Continuer avec l'API
```

### Méthode 3 : Obtenir les informations sans bloquer

```php
<?php
require_once __DIR__ . '/middleware/ip-auth.php';

$authInfo = getIPAuthInfo();

// $authInfo contient :
// [
//   'ip' => '192.168.1.100',
//   'authorized' => true/false,
//   'mode' => 'whitelist',
//   'reason' => 'IP not in whitelist' // si non autorisé
// ]
```

## Formats d'IP supportés

### IP simple
```env
ALLOWED_IPS=192.168.1.100,127.0.0.1
```

### Notation CIDR (plage d'IPs)
```env
ALLOWED_IPS=192.168.1.0/24,10.0.0.0/8
```

### Wildcards (*)
```env
ALLOWED_IPS=192.168.1.*,10.0.*.*
```

### Mélange de formats
```env
ALLOWED_IPS=127.0.0.1,192.168.1.0/24,10.0.*.*,172.16.50.100
```

## Modes de fonctionnement

### Mode Whitelist (Liste Blanche) - RECOMMANDÉ

Seules les IPs spécifiées sont autorisées, toutes les autres sont bloquées.

```env
IP_AUTH_MODE=whitelist
ALLOWED_IPS=192.168.1.0/24,10.0.0.50
```

**Utilisation recommandée :**
- Environnements de production
- APIs sensibles
- Accès restreints à des IPs connues

### Mode Blacklist (Liste Noire)

Toutes les IPs sont autorisées sauf celles spécifiées.

```env
IP_AUTH_MODE=blacklist
BLOCKED_IPS=123.456.789.0,45.67.89.0/24
```

**Utilisation recommandée :**
- Environnements de développement
- Bloquer des IPs malveillantes spécifiques
- APIs publiques avec quelques restrictions

## Gestion des Proxies

Le middleware détecte automatiquement l'IP réelle du client même derrière :
- Cloudflare (`CF-Connecting-IP`)
- Proxies reverse (`X-Forwarded-For`)
- Nginx (`X-Real-IP`)
- Load balancers

## Exemples de configuration

### Développement local uniquement
```env
IP_AUTH_MODE=whitelist
ALLOWED_IPS=127.0.0.1,::1
```

### Réseau d'entreprise
```env
IP_AUTH_MODE=whitelist
ALLOWED_IPS=192.168.1.0/24,172.16.0.0/16
```

### Bloquer des IPs malveillantes
```env
IP_AUTH_MODE=blacklist
BLOCKED_IPS=123.45.67.89,98.76.54.0/24
```

### Production avec IPs spécifiques
```env
IP_AUTH_MODE=whitelist
ALLOWED_IPS=203.0.113.10,203.0.113.11,198.51.100.0/24
```

## Réponse en cas de refus

Le client reçoit une réponse HTTP 403 avec :

```json
{
  "success": false,
  "error": "Access Forbidden",
  "message": "Your IP address is not authorized to access this API",
  "ip": "123.45.67.89",
  "reason": "IP not in whitelist"
}
```

## Migration depuis un système basé sur les positions

### Avant (autorisation par position)
```php
if ($user['position'] !== 'ADMIN') {
    http_response_code(403);
    exit;
}
```

### Après (autorisation par IP)
```php
require_once __DIR__ . '/middleware/ip-auth.php';
requireIPAuthorization();
```

## Sécurité

1. **Mode whitelist recommandé** pour la production
2. **Ne jamais commiter** le fichier `.env` avec les IPs de production
3. **Utiliser HTTPS** pour chiffrer les communications
4. **Combiner avec d'autres mesures** : authentification JWT, rate limiting, etc.
5. **Logger les accès refusés** pour détecter les tentatives d'intrusion

## Tests

### Tester votre configuration
Créez un fichier `test-ip-auth.php` :

```php
<?php
require_once __DIR__ . '/middleware/ip-auth.php';

$authInfo = getIPAuthInfo();

header('Content-Type: application/json');
echo json_encode($authInfo, JSON_PRETTY_PRINT);
```

Accédez à ce fichier pour voir les informations d'autorisation.

## Support

Pour toute question ou problème, consultez la documentation ou contactez l'équipe de développement.
