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 rca dupont
./bin/decrypt-user	Afficher les infos complètes d'un user	./bin/decrypt-user rca 123
./bin/reset-password	Générer et enregistrer un nouveau mot de passe	./bin/reset-password rca 123
./bin/search-email	Rechercher par email	./bin/search-email rca contact@example.com
./bin/list-users	Lister les utilisateurs	./bin/list-users dva --entite=5
./bin/search-entite	Rechercher une entité (mode interactif)	./bin/search-entite rca plumeliau
./bin/decrypt-entite	Afficher les infos complètes d'une entité	./bin/decrypt-entite rca 10
./bin/list-entites	Lister les entités	./bin/list-entites dva --stripe
./bin/list-operations	Lister les opérations	./bin/list-operations dva --entite=5
./bin/list-sectors	Lister les secteurs d'une opération	./bin/list-sectors dva --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 (DVA, RCA, PRA) via tunnels SSH
• Vérifier l'intégrité du chiffrement AES-256-CBC

🏗️ Architecture

Depuis le PC (via tunnels SSH)

PC Bureau (localhost)
    ↓ SSH Tunnels
    ├─→ IN3/dva-geo → IN3/maria3:3306 → dva_geo
    ├─→ IN3/rca-geo → IN3/maria3:3306 → rca_geo
    └─→ IN4/pra-geo → IN4/maria4:3306 → pra_geo

Depuis les containers (connexion directe)

IN3/dva-geo ──→ 13.23.33.4:3306 (maria3) → dva_geo
IN3/rca-geo ──→ 13.23.33.4:3306 (maria3) → rca_geo
IN4/pra-geo ──→ 13.23.33.4:3306 (maria4) → pra_geo

Connexions SSH

Les tunnels SSH sont gérés automatiquement via ~/.ssh/config :

• vpn-dva-geo : Container DVA sur IN3 (via VPN)
• vpn-rca-geo : Container RCA sur IN3 (via VPN)
• pra-geo : Container PRA sur IN4 (désactivé)

Note : Depuis les containers, les tunnels SSH ne sont pas nécessaires. BAO se connecte directement aux bases maria3/maria4.

📦 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

Sur le PC

cd /home/pierre/dev/geosector/bao

# Copier le template et adapter
cp config/.env.example config/.env

# Les valeurs par défaut sont configurées pour utiliser les tunnels SSH
# vers dva-geo (port 3307) et rca-geo (port 3308)
cat config/.env

Sur les containers (après déploiement)

Le script deploy-bao.sh copie automatiquement config/.env.container vers config/.env.

Cette configuration utilise les connexions directes vers maria3/maria4 (pas de tunnels SSH).

📦 Déploiement sur les containers

BAO peut être déployé sur les containers pour une utilisation directe sur les serveurs.

Déployer sur DVA (IN3/dva-geo)

cd /home/pierre/dev/geosector/bao
./deploy-bao.sh

Déployer sur RECETTE (IN3/rca-geo)

cd /home/pierre/dev/geosector/bao
./deploy-bao.sh rca

Déployer sur PRODUCTION (IN4/pra-geo)

cd /home/pierre/dev/geosector/bao
./deploy-bao.sh pra

Utiliser BAO sur un container

# Connexion au container
ssh -i ~/.ssh/id_rsa_mbpi root@195.154.80.116 'incus exec rca-geo -- bash'

# Lancer BAO
cd /var/www/geosector/bao
./bin/bao

# Ou directement un script
./bin/search-user rca dupont

🚀 Utilisation

Menu interactif principal

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

Menu avec :

1. Sélection de l'environnement (DVA/RCA/PRA)
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 dva dupont
./bin/search-user rca pv_admin
./bin/search-user dva 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 dva 123
./bin/decrypt-user rca 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 dva 123
./bin/reset-password rca 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 dva 5
./bin/decrypt-entite rca 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 dva

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

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

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

# Combinaison de filtres
./bin/list-users dva --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 dva plumeliau
./bin/search-entite rca amicale
./bin/search-entite dva 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 dva

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

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

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

Lister les opérations

# Toutes les opérations
./bin/list-operations dva

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

# Limite personnalisée
./bin/list-operations rca --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 dva --operation=123
./bin/list-sectors rca --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 dva contact@example.com
./bin/search-email rca 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 dva
./bin/_ssh-tunnel.sh open rca

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

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

📁 Structure du projet

bao/
├── README.md                 # Cette documentation
├── .gitignore               # Exclut config/.env
├── deploy-bao.sh            # Script de déploiement vers containers
│
├── config/
│   ├── .env                 # Configuration locale (gitignored)
│   ├── .env.example         # Template pour utilisation PC (tunnels SSH)
│   ├── .env.container       # Template pour utilisation containers (connexion directe)
│   └── 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"

Depuis le PC

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

# Tester manuellement la connexion au tunnel
nc -zv 127.0.0.1 3307  # Pour DVA
nc -zv 127.0.0.1 3308  # Pour RCA

Depuis un container

# Tester la connexion directe vers maria3/maria4
mysql -h 13.23.33.4 -u dva_geo_user -p dva_geo -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 rca 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 rca martin        # Trouver l'ID
./bin/reset-password rca 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 dva 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 dva --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 rca 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 dva --stripe

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

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

./bin/list-operations rca --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 dva --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 dva 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 PRA

⚠️ Attention : L'environnement PRA 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 RCA
3. Changer PRA_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