# PASSATION — Script de migration Fastmail → Google Workspace

## Objectif

Outil en ligne de commande permettant de migrer une boîte mail à la fois,
depuis Fastmail vers Google Workspace, avec création préalable du compte
Workspace de destination.

Usage cible :

```bash
migrer.sh user@domain.fr           # variante mot de passe d'app (2FA requise)
migrer-oauth.sh user@domain.fr     # variante OAuth (sans mot de passe destination)
```

## Architecture

Le script enchaîne deux étapes :

1. **Création du compte Workspace** via GAM (Google Apps Manager).
2. **Migration des mails** via `imapsync` (IMAP source → IMAP destination).

Le script demande interactivement les réglages et mots de passe. Les réglages
**non sensibles** (hôtes, ports, login source, prénom/nom, chemin de gam) sont
mémorisés dans `~/.migrer/defaults` et proposés comme valeurs par défaut au
lancement suivant. Les **mots de passe ne sont jamais stockés**.

Deux variantes coexistent :

- `migrer.sh` — destination authentifiée par **mot de passe d'application Google**
  (nécessite 2FA activée manuellement sur le compte de destination).
- `migrer-oauth.sh` — destination authentifiée en **XOAUTH2 via le service
  account GAM** (délégation domain-wide). **Aucun mot de passe IMAP destination,
  aucune 2FA à activer.** C'est la variante à privilégier, surtout pour la
  migration de plusieurs comptes.

## Dépendances

### imapsync

```bash
# Debian/Ubuntu
sudo apt install libio-socket-ssl-perl libmail-imapclient-perl \
  libdigest-md5-file-perl libterm-readkey-perl libfile-copy-recursive-perl \
  libio-tee-perl libunicode-string-perl liburi-perl libtest-mockobject-perl \
  libdata-uniqid-perl libcrypt-openssl-rsa-perl libjson-webtoken-perl

git clone https://github.com/imapsync/imapsync.git
cd imapsync && sudo cp imapsync /usr/local/bin/
```

### GAM (Google Apps Manager)

Installation puis configuration OAuth une seule fois :

```bash
bash <(curl -s -S -L https://git.io/install-gam)
gam create project
gam oauth create
```

La config GAM gère l'auth (service account + délégation domain-wide), donc
aucune clé n'est à mettre dans le script.

## Réglages à fournir (première exécution)

| Réglage | Valeur |
|---|---|
| Hôte source | `imap.fastmail.com` |
| Port source | `993` (SSL) |
| Login source | l'adresse complète |
| Mot de passe source | mot de passe d'application Fastmail (Settings → Privacy & Security → App passwords, accès IMAP) |
| Hôte destination | `imap.gmail.com` |
| Port destination | `993` (SSL) |
| Mot de passe destination (`migrer.sh`) | mot de passe d'application Google (nécessite 2FA activée) |
| Service account JSON (`migrer-oauth.sh`) | clé du service account GAM, ex. `~/.gam/oauth2service.json` |
| Prénom / Nom | pour la création du compte |
| Chemin de gam | ex. `/home/user/bin/gam7/gam` |

## La contrainte du mot de passe destination (et comment la variante OAuth la supprime)

Un compte Workspace fraîchement créé **n'a pas de mot de passe d'application**.
Tant que la 2FA n'est pas activée, on ne peut pas en générer, et l'accès IMAP
par mot de passe simple est généralement bloqué sur les Workspace récents.

Avec `migrer.sh`, le flux fiable reste manuel :

1. Créer le compte (étape GAM).
2. Se connecter une fois, activer la 2FA, générer un mot de passe d'application.
3. Lancer la migration imapsync avec ce mot de passe.

**`migrer-oauth.sh` lève cette contrainte** : imapsync s'authentifie sur Gmail
(host2) en XOAUTH2 avec le service account GAM, qui usurpe le compte de
destination via la délégation domain-wide. Plus besoin de mot de passe ni de 2FA
côté destination — l'automatisation devient bout-en-bout.

> Note : le « vrai » Data Migration Service de Google (migration IMAP par lots
> de la console Admin) n'a **pas** de commande GAM ni d'API exploitable ; la
> piste « DMS piloté par GAM » n'existe pas telle quelle. Le bénéfice visé
> (supprimer le mot de passe IMAP destination) est obtenu par le XOAUTH2
> service-account d'imapsync, plus simple et tout aussi robuste.

## Prérequis OAuth (variante `migrer-oauth.sh`, une seule fois)

Le scope `https://mail.google.com/` doit être autorisé en délégation
domain-wide pour le service account GAM. Le scope `gmail.readonly` ou
`gmail.modify` ne suffit **pas** pour l'IMAP.

```bash
gam print serviceaccount                                    # récupérer le client_id
gam update domainwidedelegation <client_id> https://mail.google.com/
gam user toi@domain.fr check serviceaccount                 # doit afficher le scope mail en PASS
```

L'autorisation couvre tout le domaine en une fois : rien à refaire par compte.

## Détails imapsync

- `--ssl1 / --ssl2` : connexions chiffrées.
- `--authmech2 XOAUTH2` + `--password2 <service_account.json>` : auth OAuth destination (variante OAuth).
- `--automap` : mappe les dossiers spéciaux (Sent/Trash/Drafts → libellés Gmail).
- `--skipcrossduplicates` : évite les doublons.
- `--justlogin` : valide uniquement la connexion (utile pour tester l'auth OAuth).
- `--dry` : test à blanc, à utiliser pour vérifier le mapping avant la vraie copie.
- Logs dans `~/.migrer/logs/`.

Avec `migrer-oauth.sh`, toute option passée après l'adresse est transmise telle
quelle à imapsync :

```bash
migrer-oauth.sh user@domain.fr --justlogin   # teste l'auth OAuth destination
migrer-oauth.sh user@domain.fr --dry         # teste le mapping, ne copie rien
migrer-oauth.sh user@domain.fr               # migration réelle
```

## État actuel

- [x] Script `migrer.sh` fonctionnel : réglages mémorisés, création de compte
      GAM (avec détection si le compte existe déjà), migration imapsync.
- [x] Variante OAuth `migrer-oauth.sh` (XOAUTH2 service-account, sans mot de
      passe IMAP destination ni 2FA). Remplace la piste « DMS piloté par GAM »,
      irréalisable telle quelle.
- [ ] Gestion de la migration en masse (boucle sur une liste de comptes / CSV).
- [ ] Vérification post-migration (comptage de messages source vs destination).

## Fichiers

- `migrer.sh` — variante mot de passe d'application (2FA).
- `migrer-oauth.sh` — variante OAuth service-account (recommandée).
- `~/.migrer/defaults` — valeurs par défaut de `migrer.sh` (chmod 600).
- `~/.migrer/defaults-oauth` — valeurs par défaut de `migrer-oauth.sh` (chmod 600).
- `~/.migrer/logs/` — logs imapsync horodatés par compte.

## Préférences de code

Code minimal et lisible, pas de classes inutiles, pas de commentaires quand le
nommage suffit, fichiers concis.