g9-migration/GUIDE-MATRIX.md

# Guide Matrix — utilisation et connexion

> **Objet** : rejoindre et administrer le serveur Matrix (Synapse + Element) auto-hébergé.
> **Source** : déploiement documenté dans `g9-migration/journal.md` (Phase 2, 10/10/2026) et `DOSSIER-SOFTWARE.md` S8.
> **Aucun secret dans ce guide** — les identifiants vivent dans **Vaultwarden**, jamais dans le dépôt (`.gitignore` : `matrix.env`, `*.key`, `*.cred`).

---

## 1. État du serveur

| Composant | Machine | URL | Rôle |
|-----------|---------|-----|------|
| **Synapse** (homeserver) | G9 (`.24`) | `http://192.168.1.24:8008` | Serveur Matrix (API + fédération) |
| **Element Web** (client) | G9 (`.24`) | `http://192.168.1.24:8009` | Client web, préconfiguré sur le homeserver local |
| **Salon ops** | — | `!mp7MFx9QbrJ0ARtzw…` | Canal d'alertes (watchtower, restic, n8n) — user `ops-bot` |
| **Cible TLS (Phase 4)** | — | `https://matrix.folzocorp.fr` | Accès sécurisé via Caddy (planifié, non en place) |

- Version Synapse : **1.162.0** ; version Element Web : **1.12.30**.
- `server_name` du homeserver : `192.168.1.24` → les identifiants ont la forme `@pseudo:192.168.1.24`.
- Cible finale documentée : migration Matrix + Jitsi vers le **J5040 (`.1`)** (16 Go) — voir `DOSSIER-SOFTWARE.md` S2.4/S8.

---

## 2. Connexion

### 2.1 Element Web (PC, LAN)

1. Ouvrir **`http://192.168.1.24:8009`**.
2. Le homeserver est **déjà préconfiguré** (`config.json` monté en lecture seule dans le conteneur → `base_url: http://192.168.1.24:8008`). Rien à saisir.
3. Se connecter avec son compte (§3).

> ⚠️ **En `http://IP`, Element Web affiche un rond infini** (contexte non sécurisé) — lire la section **5. Dépannage** avant de diagnostiquer le serveur. Fix recommandé : tunnel `localhost` (§5.2) ou TLS Phase 4.

### 2.2 Element Android (téléphone)

1. Installer **Element** (Play Store / F-Droid).
2. À l'écran de bienvenue : **Modifier le serveur d'accueil** (Changer de serveur).
3. Saisir `http://192.168.1.24:8008` → **Suivant** → **Se connecter**.
4. Nom d'utilisateur = le pseudo **sans le domaine** (ex. `effi`, pas `@effi:192.168.1.24`) + mot de passe.

### 2.3 Element Desktop (PC)

1. Installer Element Desktop (le navigateur n'est pas concerné par la restriction de contexte sécurisé).
2. Écran de connexion → **Modifier le serveur d'accueil** → `http://192.168.1.24:8008`.

### 2.4 Accès depuis l'extérieur (hors LAN)

Matrix n'est **pas exposé** sur Internet (volontairement). Deux voies :

| Voie | Comment |
|------|---------|
| **WireGuard** (J5040 `.1`) | Se connecter au VPN depuis le téléphone/PC portable → le LAN `.1/24` est atteignable → ouvrir `http://192.168.1.24:8009` (Android : saisir directement le homeserver dans l'app) |
| **TLS Phase 4** (à faire) | Caddy + `matrix.folzocorp.fr` → l'app Element utilise `https://matrix.folzocorp.fr`, accessible de façon sécurisée |

---

## 3. Création de compte

> L'**inscription publique est désactivée** (pas de self-registration sur un serveur privé). Les comptes se créent **côté serveur**, en SSH sur le G9 (`.24`).

### 3.1 Prérequis : un compte admin Synapse

Si aucun admin n'existe, en créer un via le conteneur Synapse :

```bash
# sur .24 — trouver le nom du conteneur
docker ps --format '{{.Names}}' | grep -i synapse

# créer un utilisateur admin (le script lit le shared secret du homeserver.yaml)
docker exec -it <conteneur_synapse> register_new_matrix_user \
  -c /data/homeserver.yaml -a -u <ADMIN> -p '<MOT_DE_PASSE_ADMIN>'
```

> Si `register_new_matrix_user` refuse (pas de `registration_shared_secret` dans `homeserver.yaml`) : l'ajouter via `sudo` dans `/data/homeserver.yaml` (`registration_shared_secret: <SECRET_ALEATOIRE>`, généré par `openssl rand -hex 32`), **restart du conteneur**, relancer la commande, puis retirer le secret et restart à nouveau. Même pattern que `room_creation: true` (journal 2026-10-09). Stocker `<MOT_DE_PASSE_ADMIN>` dans **Vaultwarden**.

### 3.2 Créer les comptes (famille, bots) via l'API admin

**Étape 1 — obtenir un token admin** (login avec le compte admin) :

```bash
curl -s -X POST 'http://192.168.1.24:8008/_matrix/client/v3/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "auth": {
      "type": "m.login.password",
      "identifier": { "type": "m.id.user", "user": "<ADMIN>" },
      "passphrase": "<MOT_DE_PASSE_ADMIN>"
    }
  }'
# → réponse JSON : récupérer "access_token" (= <TOKEN_ADMIN>)
```

**Étape 2 — créer l'utilisateur** (API admin v2, `PUT` = enregistrement) :

```bash
curl -s -X PUT 'http://192.168.1.24:8008/_synapse/admin/v2/users/@<PSEUDO>:192.168.1.24' \
  -H "Authorization: Bearer <TOKEN_ADMIN>" \
  -H 'Content-Type: application/json' \
  -d '{
    "password": "<MOT_DE_PASSE_UTILISATEUR>",
    "display_name": "<Nom affiché>",
    "admin": false
  }'
# → 201 Created = compte créé
```

- `admin: true` pour un second administrateur, `false` pour la famille/bots.
- Le pseudo est en minuscules, sans espaces ni accents (règle Matrix).

### 3.3 Première connexion + chiffrement (E2E)

1. Ouvrir Element (§2), se connecter avec `@<PSEUDO>:192.168.1.24` (Web/Desktop : pseudo seul suffit).
2. Element demande une **phrase de passe de récupération** (secure backup) → la **noter hors-ligne** (papier), c'est la porte de sortie du chiffrement.
3. Vérifier ses sessions : **Paramètres → Sécurité → Vérification** (QR code entre téléphone et PC) pour valider le chiffrement de bout en bout.

### 3.4 Désinscription / suppression

- **Désactiver** un compte (propre, conserve la trace) :
  ```bash
  curl -s -X POST 'http://192.168.1.24:8008/_synapse/admin/v1/deactivate/<PSEUDO>' \
    -H "Authorization: Bearer <TOKEN_ADMIN>" \
    -H 'Content-Type: application/json' \
    -d '{ "erase": true }'
  ```
- Vérifier que l'inscription publique reste fermée dans `homeserver.yaml` : `disable_registration: true` (ne pas activer `enable_registration` sans point d'accès protégé).

---

## 4. Usage type (rappel du plan, S8)

| Salon | Contenu |
|-------|---------|
| **Famille** | Messagerie quotidienne du **foyer** (complément de WhatsApp, **pas un remplacement**), visio Jitsi intégrée à Element |
| **Ops** | Alertes machine : watchtower (MAJ images), restic (backup G9), n8n — via `ops-bot` |
| **hermes** (prévu) | Salon où la famille parle à Effi (assistant, Phase 3 du second cerveau) |

---

## 5. Dépannage

### 5.1 Le rond infini dans Element Web (cause racine documentée)

**Symptôme** : page noire, spinner infini sur `http://192.168.1.24:8009`. Console (F12) :

```
Browser missing feature: 'crypto'
Browser missing feature: 'securecontext'
Error initialising Matrix session TypeError: window.crypto.randomUUID is not a function
```

**Cause** : Element ≥ 1.12 exige un **contexte sécurisé** (HTTPS, `localhost` ou `file:`). En `http://<IP>`, le navigateur coupe `crypto.randomUUID` → Element n'arrive pas à initialiser la session. **Le serveur n'y est pas pour rien.**

Anodins (à ne pas poursuivre) : `404 config.<host>.json` (config optionnelle par hôte) et `404 /_matrix/client/v1/auth_metadata` (endpoint optionnel).

**Cause secondaire** : un vieux **service worker** peut garder en cache une config obsolète (la config cassée « matrix.org » d'avant le fix du 10/10). Nettoyage : F12 → Application → Service Workers → *Unregister*, puis Storage → *Clear site data*, puis Ctrl+Maj+R.

### 5.2 Workaround sans TLS : tunnel localhost

`localhost` est un contexte sécurisé → Element fonctionne. Depuis le PC :

```bash
ssh -L 8009:192.168.1.24:8009 -L 8008:192.168.1.24:8008 <user>@192.168.1.24
# puis ouvrir http://localhost:8009
```

### 5.3 Fix définitif : TLS (Phase 4)

Caddy + `matrix.folzocorp.fr` (même pattern que `obsidian.folzocorp.fr`, journal Phase 4) → Element Web servi en HTTPS, spinner résolu, accès distant propre.

### 5.4 Commandes de diagnostic (côté serveur, tout doit répondre)

```bash
# 1) API vivante → JSON avec "versions":[...] (200)
curl -s http://192.168.1.24:8008/_matrix/client/versions

# 2) Element servi + config correcte → 200 + base_url = http://192.168.1.24:8008
curl -s http://192.168.1.24:8009/ -o /dev/null -w '%{http_code}\n'
curl -s http://192.168.1.24:8009/config.json

# 3) CORS (sans lui, Element web est muet) → Access-Control-Allow-Origin: *
curl -s -D - -o /dev/null -H "Origin: http://192.168.1.24:8009" \
  http://192.168.1.24:8008/_matrix/client/versions | grep -i access-control

# 4) Conteneurs
docker ps --format '{{.Names}}\t{{.Status}}' | grep -Ei 'synapse|element'
```

**Résultats vérifiés le 11/10/2026** : 1) `200` + versions r0.0.1→v1.12 ; 2) `200` + `base_url: http://192.168.1.24:8008` ; 3) `Access-Control-Allow-Origin: *` ; 4) synapse `Synapse/1.162.0` UP. Si ces 4 tests passent et qu'Element tourne en rond → problème 100 % navigateur (§5.1/5.2).

### 5.5 Alertes ops absentes du salon ops

- Vérifier le token `ops-bot` : côté G9, `/etc/restic/matrix.env` (root, `600`) pour restic ; workflow n8n « Watchtower Notification » pour les MAJ d'images.
- Test d'envoi direct :
  ```bash
  curl -s -X POST 'http://192.168.1.24:8008/_matrix/client/v3/rooms/!mp7MFx9QbrJ0ARtzw…/send/m.room.message/test1' \
    -H "Authorization: Bearer <TOKEN_OPS_BOT>" \
    -H 'Content-Type: application/json' \
    -d '{"msgtype":"m.text","body":"test alerte"}'
  # → 200 + {"event_id":"$…"}
  ```

---

## 6. Sécurité (règles du projet)

| Règle | Application Matrix |
|-------|--------------------|
| Secrets hors dépôt | Token admin, mot de passe admin, `matrix.env` → **Vaultwarden** / root only, jamais git |
| Pas d'exposition Internet | Accès LAN ou WireGuard ; TLS Phase 4 pour l'exposition contrôlée |
| 2FA | À activer sur les comptes admin (S9 : 2FA sur tous les services exposés) |
| Comptes famille | `admin: false`, mot de passe unique par personne, phrase de récupération E2E notée hors-ligne |

---

*Guide créé le 11/10/2026 — état vérifié ce jour sur `.24` (Synapse 1.162.0, Element 1.12.30). À réaligner quand Matrix migrera vers le J5040 (`.1`) et que `matrix.folzocorp.fr` (Caddy TLS) sera en place.*