# 05 — Intégration Google (OAuth & APIs)

## Principe

**Modèle « compte partagé »** : seul le **Super Admin** lie un compte Google (via `/settings`,
réservé au super_admin). Le site obtient un **refresh token** (chiffré au repos) et l'utilise
**pour tous les utilisateurs** via `getOwnerGoogleClient()` (cf. `backend/src/lib/data-owner.ts`).
Les admins/users n'ont pas de connexion Google personnelle.

## Configuration côté Google Cloud (à faire dans la console Google)

1. Créer (ou réutiliser) un **projet Google Cloud**.
2. Activer les APIs : **Google Calendar API**, **Gmail API** (puis People/Tasks plus tard).
3. Configurer l'**écran de consentement OAuth** :
   - Type : *External* (ou *Internal* si compte Google Workspace).
   - Tant que l'app est en mode test : ajouter les utilisateurs autorisés (les quelques comptes).
4. Créer des **identifiants OAuth 2.0 (Web application)** :
   - **Authorized redirect URI** : `https://leperelion.fr/backend/google/oauth/callback`
     (et `http://localhost:4002/google/oauth/callback` pour le dev si besoin).
5. Récupérer **Client ID** et **Client Secret** → à saisir dans la **page de configuration
   Super Admin** : `/admin/config` (et non plus dans le `.env`).

> ⚠️ Les valeurs Client ID/Secret sont des **secrets**. Le **Client Secret est chiffré au repos**
> (AES-GCM) dans la table `AppSetting` et n'est jamais renvoyé en clair par l'API
> (`GET /config` expose seulement `clientSecretSet: true/false`).
>
> **Source de la config** (priorité) : valeurs saisies dans `/admin/config` (base `AppSetting`)
> → sinon repli sur le `.env` (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_REDIRECT_URI`).
> Implémentation : `backend/src/lib/config-store.ts` (`getGoogleConfig`).

## Scopes (permissions)

Principe : **permissions minimales**. À ajuster selon le besoin final (lecture seule vs
lecture/écriture), à confirmer avec l'utilisateur.

| Service  | Scope proposé                                              | Usage                          |
|----------|-----------------------------------------------------------|--------------------------------|
| Calendar | `https://www.googleapis.com/auth/calendar`                | Lire/créer/modifier événements |
| Gmail    | `https://www.googleapis.com/auth/gmail.modify`            | Lire, marquer, archiver        |
| Gmail*   | `https://www.googleapis.com/auth/gmail.send`              | (si envoi requis)              |
| Drive    | `https://www.googleapis.com/auth/drive`                   | Parcourir/lire + gérer (upload/renommer/supprimer) |
| (base)   | `openid email profile`                                    | Identité du compte lié         |

> ➕ **Ajout d'un scope = re-consentement** : quand on ajoute une permission (ex. Drive),
> l'utilisateur doit **reconnecter** son compte Google (`/settings`) pour que le nouveau scope
> soit accordé. Tant qu'il ne l'a pas fait, les appels concernés renvoient 409 `reconnect`
> (détecté via `insufficientPermissions`). Penser aussi à **activer l'API** correspondante dans
> Google Cloud (Drive API).

\* À confirmer : la boîte mail doit-elle permettre **l'envoi** de mails ou la **lecture/gestion**
seule ? (voir [08_QUESTIONS_RESTANTES.md](08_QUESTIONS_RESTANTES.md))

## Flow OAuth (côté backend)

1. `GET /backend/google/oauth/start` → redirige vers Google (consent screen), avec
   `access_type=offline` et `prompt=consent` (pour obtenir un refresh token), et un `state` anti-CSRF.
2. Google redirige vers `GET /backend/google/oauth/callback?code=...&state=...`.
3. Le backend échange le `code` contre `{ access_token, refresh_token, expiry }`.
4. Le **refresh token est chiffré** (AES-256-GCM, clé `LEPERELION_ENCRYPTION_KEY`) et stocké
   dans la table `google_account` liée à l'utilisateur.
5. À chaque appel API : on régénère un access token à partir du refresh token (lib `googleapis`
   gère le rafraîchissement automatiquement).

## Stockage des tokens

- Table `google_account` (voir [06_MODELE_DONNEES.md](06_MODELE_DONNEES.md)) :
  `user_id`, `google_sub`, `email`, `refresh_token_enc`, `scopes`, `connected_at`.
- **Jamais** de token en clair en base ni dans les logs.
- Révocation : endpoint « Déconnecter Google » qui révoque le token côté Google et supprime la ligne.

## Librairie

- Backend : **`googleapis`** (client officiel Node) + `google-auth-library` pour le flow OAuth.

## Quotas & limites

- Surveiller les quotas Gmail/Calendar (requêtes/jour). Prévoir pagination et cache léger côté
  backend si nécessaire (V2).