geo/bao/README.md

# BAO - Back-office Admin Operations

Toolkit d'administration pour consulter et gérer les données chiffrées de l'API Geosector.

## 🚀 Scripts disponibles

| Script | Description | Exemple |
|--------|-------------|---------|
| `./bin/bao` | Menu interactif principal | `./bin/bao` |
| `./bin/search-user` | Rechercher un user par nom/prénom/username/secteur | `./bin/search-user rec dupont` |
| `./bin/decrypt-user` | Afficher les infos complètes d'un user | `./bin/decrypt-user rec 123` |
| `./bin/reset-password` | Générer et enregistrer un nouveau mot de passe | `./bin/reset-password rec 123` |
| `./bin/search-email` | Rechercher par email | `./bin/search-email rec contact@example.com` |
| `./bin/list-users` | Lister les utilisateurs | `./bin/list-users dev --entite=5` |
| `./bin/search-entite` | Rechercher une entité (mode interactif) | `./bin/search-entite rec plumeliau` |
| `./bin/decrypt-entite` | Afficher les infos complètes d'une entité | `./bin/decrypt-entite rec 10` |
| `./bin/list-entites` | Lister les entités | `./bin/list-entites dev --stripe` |
| `./bin/list-operations` | Lister les opérations | `./bin/list-operations dev --entite=5` |
| `./bin/list-sectors` | Lister les secteurs d'une opération | `./bin/list-sectors dev --operation=123` |

## 📋 Vue d'ensemble

BAO est un ensemble de scripts **indépendants de l'API** permettant de :
- Consulter les données **déchiffrées** des utilisateurs et entités
- Rechercher dans les champs chiffrés (username, nom, email)
- Réinitialiser les mots de passe utilisateurs
- Se connecter aux **3 environnements** (DEV, REC, PROD) via tunnels SSH
- Vérifier l'intégrité du chiffrement AES-256-CBC

## 🏗️ Architecture

```
PC Bureau (localhost)
    ↓ SSH Tunnels
    ├─→ IN3/dva-geo (DEV)  → localhost:3306 → geo_app
    ├─→ IN3/rca-geo (REC)  → localhost:3306 → geo_app
    └─→ IN4/pra-geo (PROD) → localhost:3306 → pra_geo
```

### Connexions SSH

Les tunnels SSH sont gérés automatiquement via `~/.ssh/config` :
- **vpn-dva-geo** : Container DEV sur IN3 (via VPN)
- **vpn-rca-geo** : Container REC sur IN3 (via VPN)
- **pra-geo** : Container PROD sur IN4 (désactivé)

## 📦 Installation

### 1. Prérequis

```bash
# PHP 8.3+ avec extensions
php -v
php -m | grep -E 'pdo|openssl|mbstring'

# SSH configuré dans ~/.ssh/config
ssh vpn-dva-geo 'echo OK'
ssh vpn-rca-geo 'echo OK'
```

### 2. Configuration

```bash
cd /home/pierre/dev/geosector/bao

# Le fichier .env est déjà créé avec les bonnes valeurs
# Vérifier la configuration
cat config/.env
```

## 🚀 Utilisation

### Menu interactif principal

```bash
cd /home/pierre/dev/geosector/bao
./bin/bao
```

Menu avec :
1. Sélection de l'environnement (DEV/REC/PROD)
2. Actions disponibles (liste, recherche, décryptage)
3. Gestion automatique des tunnels SSH

### Scripts individuels

#### Rechercher un utilisateur

```bash
# Rechercher par nom, prénom, username ou secteur
./bin/search-user dev dupont
./bin/search-user rec pv_admin
./bin/search-user dev jean
```

**Fonctionnalités :**
- Déchiffre **tous** les utilisateurs pour chercher
- Cherche dans : `encrypted_user_name`, `encrypted_name`, `first_name`, `sect_name`
- Affiche un tableau avec les résultats
- Propose d'afficher les détails complets si 1 seul résultat

#### Décrypter un utilisateur

```bash
./bin/decrypt-user dev 123
./bin/decrypt-user rec 456
```

**Affiche :**
- Username, email, nom, prénom (déchiffrés)
- Téléphones (déchiffrés)
- Rôle, entité, dates

#### Réinitialiser un mot de passe

```bash
./bin/reset-password dev 123
./bin/reset-password rec 456
```

**Fonctionnalités :**
- Affiche les infos de l'utilisateur
- Demande confirmation
- Génère un mot de passe sécurisé (12-20 caractères, conforme aux règles API)
- Hash avec bcrypt et met à jour la base
- **Affiche le mot de passe en clair** (à sauvegarder)

#### Décrypter une entité (amicale)

```bash
./bin/decrypt-entite dev 5
./bin/decrypt-entite rec 10
```

**Affiche :**
- Nom, email, téléphones (déchiffrés)
- Adresse complète
- IBAN/BIC (déchiffrés)
- Configuration (Stripe, mots de passe, etc.)
- Statistiques (nb users, opérations)

#### Lister les utilisateurs

```bash
# Tous les utilisateurs (limite 50)
./bin/list-users dev

# Filtrer par entité
./bin/list-users dev --entite=5

# Filtrer par rôle
./bin/list-users rec --role=2

# Limite personnalisée
./bin/list-users dev --limit=100

# Combinaison de filtres
./bin/list-users dev --entite=5 --role=2 --limit=20
```

**Affiche :** Tableau avec username, email, nom (déchiffrés)

#### Rechercher une entité

```bash
# Rechercher par nom, adresse, ville ou email
./bin/search-entite dev plumeliau
./bin/search-entite rec amicale
./bin/search-entite dev appli
```

**Fonctionnalités :**
- Déchiffre **toutes** les entités pour chercher
- Cherche dans : `encrypted_name`, `encrypted_email`, `adresse1`, `adresse2`, `ville`
- Affiche un tableau numéroté avec les résultats
- **Mode interactif** :
  1. Détail d'une entité → appelle `decrypt-entite`
  2. Opérations d'une entité → appelle `list-operations`
  3. Membres d'une entité → appelle `list-users`

#### Lister les entités

```bash
# Toutes les entités
./bin/list-entites dev

# Uniquement celles avec Stripe activé
./bin/list-entites dev --stripe

# Limite personnalisée
./bin/list-entites rec --limit=20
```

**Affiche :** Tableau avec nom, email (déchiffrés), stats

#### Lister les opérations

```bash
# Toutes les opérations
./bin/list-operations dev

# Opérations d'une entité spécifique
./bin/list-operations dev --entite=5

# Limite personnalisée
./bin/list-operations rec --entite=10 --limit=20
```

**Affiche :** Tableau avec entité, libellé, dates, nb passages, nb users, nb secteurs

#### Lister les secteurs d'une opération

```bash
# Secteurs d'une opération spécifique
./bin/list-sectors dev --operation=123
./bin/list-sectors rec --operation=456
```

**Fonctionnalités :**
- Affiche le libellé de l'opération
- Liste tous les secteurs (actifs et inactifs)
- Compte le nombre d'utilisateurs par secteur (depuis `ope_users_sectors`)
- Compte le nombre de passages par secteur
- Affiche des statistiques globales (total users, passages, secteurs actifs)

**Affiche :** Tableau avec ID, libellé, couleur, nb users, nb passages, actif, date création

#### Rechercher par email

```bash
./bin/search-email dev contact@example.com
./bin/search-email rec admin@amicale.fr
```

**Fonctionnalités :**
- Déchiffre **tous** les emails pour chercher
- Affiche **tous** les comptes avec cet email (système autorise les doublons)
- Propose d'afficher les détails complets si 1 seul résultat

### Gestion des tunnels SSH

```bash
# Afficher l'état des tunnels
./bin/_ssh-tunnel.sh status

# Ouvrir un tunnel manuellement
./bin/_ssh-tunnel.sh open dev
./bin/_ssh-tunnel.sh open rec

# Fermer un tunnel
./bin/_ssh-tunnel.sh close dev

# Fermer tous les tunnels
./bin/_ssh-tunnel.sh close-all
```

## 📁 Structure du projet

```
bao/
├── README.md                 # Cette documentation
├── .gitignore               # Exclut config/.env
│
├── config/
│   ├── .env                 # Configuration (gitignored)
│   ├── .env.example         # Template
│   └── database.php         # Classe DatabaseConfig
│
├── lib/
│   ├── CryptoService.php    # Chiffrement/déchiffrement AES-256-CBC
│   ├── DatabaseConnection.php # Connexion PDO aux bases
│   └── helpers.php          # Fonctions utilitaires (affichage, couleurs)
│
└── bin/
    ├── bao                  # Script principal (menu interactif)
    ├── search-user          # Rechercher un utilisateur
    ├── decrypt-user         # Décrypter un utilisateur
    ├── reset-password       # Réinitialiser un mot de passe
    ├── search-email         # Rechercher par email
    ├── list-users           # Lister les utilisateurs
    ├── search-entite        # Rechercher une entité (interactif)
    ├── decrypt-entite       # Décrypter une entité
    ├── list-entites         # Lister les entités
    ├── list-operations      # Lister les opérations
    ├── list-sectors         # Lister les secteurs d'une opération
    └── _ssh-tunnel.sh       # Helper gestion tunnels SSH
```

## 🔐 Sécurité

### Chiffrement

L'API utilise **deux méthodes de chiffrement AES-256-CBC** différentes :

#### 1. Données "Searchable" (recherche)
- **Champs** : `encrypted_user_name`, `encrypted_email`
- **IV** : Fixe (16 bytes de `\0`)
- **Format** : `base64(encrypted_data)`
- **Usage** : Permet la recherche par égalité dans la base

#### 2. Données avec IV aléatoire
- **Champs** : `encrypted_name`, `encrypted_phone`, `encrypted_mobile`, `encrypted_iban`, `encrypted_bic`
- **IV** : Aléatoire (16 bytes)
- **Format** : `base64(IV + encrypted_data)`
- **Usage** : Sécurité maximale, pas de recherche directe

**Clé de chiffrement** : Base64 encodée (32 bytes) partagée avec l'API

### Données chiffrées

**Utilisateurs (`users`) :**
- `encrypted_user_name` → Username (searchable)
- `encrypted_email` → Email (searchable)
- `encrypted_name` → Nom complet (IV aléatoire)
- `encrypted_phone` → Téléphone fixe (IV aléatoire)
- `encrypted_mobile` → Téléphone mobile (IV aléatoire)

**Entités (`entites`) :**
- `encrypted_name` → Nom de l'amicale (IV aléatoire)
- `encrypted_email` → Email (searchable)
- `encrypted_phone` → Téléphone (IV aléatoire)
- `encrypted_mobile` → Mobile (IV aléatoire)
- `encrypted_iban` → Coordonnées bancaires (IV aléatoire)
- `encrypted_bic` → Code BIC (IV aléatoire)

### Bonnes pratiques

✅ **Faire :**
- Garder `.env` hors du versioning (déjà dans `.gitignore`)
- Fermer les tunnels après usage (`Ctrl+C` ou `close-all`)
- Utiliser le menu interactif pour les tâches courantes

❌ **Ne pas faire :**
- Partager la clé de chiffrement (`ENCRYPTION_KEY`)
- Laisser les tunnels ouverts en permanence
- Exporter les données déchiffrées sans précaution

## 🛠️ Dépannage

### Erreur : "Impossible d'ouvrir le tunnel SSH"

```bash
# Vérifier la connexion SSH
ssh dva-geo 'echo OK'

# Vérifier qu'aucun processus n'utilise le port
lsof -i :3307
lsof -i :3308
lsof -i :3309

# Fermer les tunnels zombies
./bin/_ssh-tunnel.sh close-all
```

### Erreur : "Impossible de se connecter à la base"

```bash
# Vérifier que le tunnel est actif
./bin/_ssh-tunnel.sh status

# Tester manuellement
ssh dva-geo 'mysql -u geo_app_user_dev -p geo_app -e "SELECT 1"'
```

### Erreur : "Échec du déchiffrement"

```bash
# Vérifier la clé de chiffrement
grep ENCRYPTION_KEY config/.env

# Comparer avec l'API
grep encryption_key ../api/src/Config/AppConfig.php
```

### Permissions refusées sur les scripts

```bash
# Rendre tous les scripts exécutables
chmod +x bin/*
```

## 📊 Exemples d'utilisation

### Cas d'usage 1 : Rechercher un utilisateur par nom

```bash
./bin/search-user rec dupont
```

Résultat : Tableau des utilisateurs contenant "dupont" (nom, prénom, username ou secteur)

### Cas d'usage 2 : Réinitialiser le mot de passe d'un utilisateur

```bash
./bin/search-user rec martin        # Trouver l'ID
./bin/reset-password rec 56930      # Réinitialiser avec l'ID
```

Résultat : Nouveau mot de passe généré et affiché en clair

### Cas d'usage 3 : Trouver tous les comptes d'un email

```bash
./bin/search-email dev contact@amicale.fr
```

Résultat : Liste tous les utilisateurs avec cet email (peut être multiple)

### Cas d'usage 4 : Lister les admins d'une amicale

```bash
./bin/list-users dev --entite=5 --role=2
```

Résultat : Tableau des administrateurs (rôle 2) de l'entité 5

### Cas d'usage 5 : Explorer une entité (mode interactif)

```bash
./bin/search-entite rec plumeliau    # Rechercher l'entité
# Sélectionner n° de ligne: 1
# Choisir action: 2 (Opérations)
```

Résultat : Workflow complet pour explorer une entité et ses données liées

### Cas d'usage 6 : Vérifier les entités avec Stripe

```bash
./bin/list-entites dev --stripe
```

Résultat : Toutes les amicales ayant activé Stripe Connect

### Cas d'usage 7 : Lister les opérations d'une entité

```bash
./bin/list-operations rec --entite=662
```

Résultat : Tableau des opérations avec stats (passages, users, secteurs)

### Cas d'usage 8 : Explorer les secteurs d'une opération

```bash
./bin/list-sectors dev --operation=123
```

Résultat : Tableau des secteurs avec nb users/passages + stats globales

### Cas d'usage 9 : Audit complet d'un utilisateur

```bash
./bin/decrypt-user dev 123
```

Résultat : Toutes les informations déchiffrées + métadonnées

## 🔄 Évolutions futures

### À court terme
- [ ] Export CSV avec données déchiffrées
- [ ] Statistiques globales par environnement
- [x] ~~Recherche par nom (déchiffré)~~ ✓ Implémenté (`search-user`)
- [x] ~~Réinitialisation de mots de passe~~ ✓ Implémenté (`reset-password`)

### À moyen terme
- [ ] Vérification HIBP pour `reset-password`
- [ ] Version Go pour performances accrues
- [ ] Cache local des données déchiffrées
- [ ] Interface TUI avec bibliotèque comme `gum`

### À long terme
- [ ] Modification de données complètes (avec validation)
- [ ] Audit trail des accès
- [ ] Synchronisation inter-environnements

## 📝 Notes

### Environnement PROD

⚠️ **Attention :** L'environnement PROD n'est **pas encore créé** (base de données inexistante).

Pour l'activer :
1. Créer la base `pra_geo` sur IN4/maria4
2. Migrer les données depuis REC
3. Changer `PROD_ENABLED=true` dans `config/.env`

### Comptes multiples par email

Le système Geosector **autorise plusieurs comptes avec le même email** (choix client).

Le script `search-email` gère cette particularité en affichant **tous** les comptes trouvés.

## 🤝 Support

Pour toute question ou amélioration :
1. Consulter le TECHBOOK de l'API : `../api/docs/TECHBOOK.md`
2. Vérifier les logs SSH : `~/.ssh/`
3. Tester la connexion directe aux containers

## 📜 Licence

Usage interne - Projet Geosector © 2025