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

# 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

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

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

# 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

./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

./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)

./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

# 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é

# 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

# 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

# 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

# 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

./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

# 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"

# 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"

# 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"

# 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

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

📊 Exemples d'utilisation

Cas d'usage 1 : Rechercher un utilisateur par nom

./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

./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

./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

./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)

./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

./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é

./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

./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

./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
• Recherche par nom (déchiffré) ✓ Implémenté (search-user)
• 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