feat: add recovery key support for E2EE agents, including configuration and documentation updates

docs/creating-agents.md

@@ -208,28 +208,67 @@ Esto hace:
 Sin este paso, los mensajes del bot mostrarán: **"Encrypted by a device not verified by its owner"**.
 
 ```bash
-go run -tags goolm ./cmd/verify \
-  --homeserver "https://matrix-af2f3d.organic-machine.com" \
+./bin/verify \
+  --homeserver "$MATRIX_HOMESERVER" \
   --username "<agent-id>" \
-  --password "<password_del_bot>" \
-  --token "<access_token>" \
-  --store "./agents/<agent-id>/data/crypto/"
+  --password "$MATRIX_PASSWORD_<AGENT>" \
+  --token "$MATRIX_TOKEN_<AGENT>" \
+  --store "./agents/<agent-id>/data/crypto/" \
+  --pickle-key "$PICKLE_KEY_<AGENT>"
 ```
 
 **Qué hace:**
-1. Inicializa el crypto helper de mautrix
-2. Genera claves de cross-signing (master + self-signing)
+1. Inicializa el crypto helper de mautrix (usando el mismo store y pickle key que el agente)
+2. Genera claves de cross-signing (master + self-signing + user-signing)
 3. Las sube al homeserver usando UIA con la password del bot
-4. Firma el device del bot con la self-signing key
+4. Las almacena cifradas en SSSS (Server-Side Secret Storage) en el servidor
+5. Imprime un **recovery key** (base58) que permite recuperar las claves privadas
 
-**Importante:** Si se cambia la password del bot (admin API), el token anterior se invalida. Hay que:
+### 5.1 Guardar el recovery key
+
+El comando imprime algo como:
+
+```
+─── IMPORTANT: Save the recovery key ───
+SSSS_RECOVERY_KEY_MI_BOT=EsXX YYYY ZZZZ ...
+```
+
+**Añadir al `.env`** (con comillas, el recovery key tiene espacios):
+
+```bash
+SSSS_RECOVERY_KEY_MI_BOT="EsXX YYYY ZZZZ ..."
+```
+
+### 5.2 Configurar recovery_key_env en config.yaml
+
+```yaml
+encryption:
+  enabled: true
+  store_path: "./agents/<agent-id>/data/crypto/"
+  pickle_key_env: PICKLE_KEY_<AGENT>
+  trust_mode: tofu
+  recovery_key_env: SSSS_RECOVERY_KEY_<AGENT>   # ← NUEVO
+```
+
+Esto permite que el agente recupere automáticamente las cross-signing private keys desde SSSS cada vez que arranca. Sin esto, las keys solo existen en memoria durante la sesión de verify.
+
+**Logs esperados al arrancar con recovery key configurado:**
+```
+INFO cross-signing private keys fetched from SSSS
+INFO e2ee ready
+```
+
+### 5.3 Si se cambia la password del bot
+
+Cambiar la password (admin API) invalida el token anterior. Hay que:
 1. Re-login para obtener nuevo token
-2. Actualizar `MATRIX_TOKEN_<AGENT>` en `.env`
+2. Actualizar `MATRIX_TOKEN_<AGENT>` y `MATRIX_PASSWORD_<AGENT>` en `.env`
 3. Actualizar `device_id` en `config.yaml`
 4. Borrar el crypto store viejo (`agents/<id>/data/crypto/crypto.db`)
-5. Re-ejecutar `cmd/verify`
+5. Re-ejecutar `cmd/verify` → obtener nuevo recovery key
+6. Actualizar `SSSS_RECOVERY_KEY_<AGENT>` en `.env`
 
-**Nota:** El pickle key (`PICKLE_KEY_<AGENT>`) NO cambia al rotar el token. Solo se regenera si se pierde. Ver `docs/e2ee.md`.
+**Nota:** El pickle key (`PICKLE_KEY_<AGENT>`) NO cambia al rotar el token. Solo se regenera si se pierde.
 
 ## Paso 6: Arrancar el agente
 
@@ -286,17 +325,24 @@ tail -f run/<agent-id>.log
 # 5. Avatar y displayname
 ./dev-scripts/avatar.sh <id> static/<imagen>.jpg
 
-# 6. Verificación E2EE
-go run -tags goolm ./cmd/verify \
+# 6. Generar pickle key (si no existe)
+openssl rand -hex 32  # → guardar como PICKLE_KEY_<AGENT> en .env
+
+# 7. Verificación E2EE + recovery key
+./bin/verify \
   --homeserver "$MATRIX_HOMESERVER" \
   --username "<id>" \
   --password "$MATRIX_PASSWORD_<AGENT>" \
-  --token "$MATRIX_TOKEN_<AGENT>"
+  --token "$MATRIX_TOKEN_<AGENT>" \
+  --store "./agents/<id>/data/crypto/" \
+  --pickle-key "$PICKLE_KEY_<AGENT>"
+# → Guardar SSSS_RECOVERY_KEY_<AGENT> en .env (con comillas)
+# → Añadir recovery_key_env al config.yaml
 
-# 7. Arrancar
+# 8. Arrancar
 ./dev-scripts/start.sh <id>
 
-# 8. Verificar
+# 9. Verificar
 tail -f run/<id>.log
 ```
 
@@ -308,7 +354,9 @@ tail -f run/<id>.log
 | `M_UNKNOWN_TOKEN` | Token invalidado (password cambiada) | Re-login, actualizar `.env` |
 | `mismatching device ID` | Crypto store con device viejo | Borrar `agents/<id>/data/crypto/crypto.db`, actualizar `device_id` en config |
 | `olm account not marked as shared` | Crypto store inconsistente | Auto-recovery lo resuelve al reiniciar. Si persiste: borrar crypto.db |
-| `"Encrypted by device not verified"` | Falta cross-signing | Ejecutar `cmd/verify` |
+| `"Encrypted by device not verified"` | Falta cross-signing | Ejecutar `cmd/verify` con `--store` y `--pickle-key` del agente, guardar recovery key en `.env` |
+| `cross-signing private keys not available` | Recovery key no configurada | Ejecutar `cmd/verify`, guardar recovery key, configurar `recovery_key_env` |
+| `verify recovery key: invalid` | Recovery key incorrecta | Re-ejecutar `cmd/verify` para generar nueva recovery key |
 | Bot no responde | Reglas no matchean | Verificar que hay regla catch-all para DMs/mentions |
 | `no rules registered for agent` | ID no está en `rulesRegistry` | Añadir en `cmd/launcher/main.go` |
 | Bot muere al arrancar | Revisar logs | `tail -f run/<id>.log` |