feat(matrix): MAS migration helpers + 2 flows + 15 issues + capability group

Helper functions (matrix-mas capability group):
- mas_client_register_bash_infra: register/sync OAuth clients via mas-cli
- mas_syn2mas_migration_bash_infra: dry-run + apply user migration to MAS
- synapse_msc3861_enable_go_infra: edit homeserver.yaml MSC3861 block (with diff)
- wellknown_oidc_patch_go_infra: patch well-known JSON with msc2965.authentication
- synapse_login_flows_check_go_infra: health-check post-migration login flows

Flows + issues for custom Matrix clients (PC + Android):
- 0010 matrix-client-pc: Wails + React+Mantine (issues 0147-0153)
- 0011 matrix-client-android: Kotlin + Compose (issues 0154-0161)
- 0162 enable MAS as auth provider (Synapse delegate) — EXECUTED on VPS
- 0163 custom admin panel propio (sustituye synapse-admin)

Production state (organic-machine.com):
- Synapse migrated SQLite -> Postgres
- MSC3861 active, password_config disabled
- 21 users + 41 access_tokens migrated via syn2mas
- 4 MAS clients registered (element, matrix_pc, matrix_android, admin_panel)
- synapse-admin container removed + Coolify route deleted
- well-known patched with org.matrix.msc2965.authentication

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

bash/functions/infra/mas_client_register.md

@@ -0,0 +1,89 @@
+---
+name: mas_client_register
+kind: function
+lang: bash
+domain: infra
+version: "0.1.0"
+purity: impure
+signature: "mas_client_register(ssh_host: string, container: string, config_file: string, dry_run: bool) -> json"
+description: "Registra y sincroniza clientes OAuth en Matrix Authentication Service (MAS) ejecutando mas-cli config sync dentro del container Docker remoto via SSH. Verifica sintaxis YAML, soporte dry-run para ver diff antes de aplicar, y emite JSON estructurado con resultado. Idempotente: re-ejecucion con misma config no genera cambios."
+tags: [matrix, mas, oauth, oidc, migration, mas-migration, infra, docker, ssh, matrix-mas]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: ssh_host
+    desc: "alias SSH del VPS donde corre MAS (ej. organic-machine.com). Debe estar en ~/.ssh/config con key auth."
+  - name: container
+    desc: "nombre del container Docker con MAS (ej. element_matrix_chat-mas-1). El config dentro del container se espera en /data/config.yaml."
+  - name: config_file
+    desc: "ruta absoluta en el VPS al archivo mas/config.yaml (ej. /home/ubuntu/CodeProyects/element_matrix_chat/mas/config.yaml). MAS lo monta como /data/config.yaml."
+  - name: dry_run
+    desc: "flag opcional --dry-run: ejecuta mas-cli config dump y devuelve el estado sin aplicar cambios. Util para verificar antes de activar MSC3861."
+output: "JSON con: status ('ok'|'dry-run'|'error'), applied (bool), clients_total (int), clients_diff (array de lineas del output de mas-cli), stderr (string con logs de error si aplica)."
+tested: true
+tests:
+  - "help flag emite JSON parseable"
+  - "args faltantes retornan JSON de error sin ssh"
+  - "jq disponible en host local"
+test_file_path: "bash/functions/infra/mas_client_register_test.sh"
+file_path: "bash/functions/infra/mas_client_register.sh"
+---
+
+## Ejemplo
+
+```bash
+# Dry-run: verificar que clients se aplicarian correctamente
+source bash/functions/infra/mas_client_register.sh
+
+mas_client_register \
+  --ssh-host organic-machine.com \
+  --container element_matrix_chat-mas-1 \
+  --config-file /home/ubuntu/CodeProyects/element_matrix_chat/mas/config.yaml \
+  --dry-run
+
+# Aplicar sync real (con --prune para eliminar clients viejos)
+mas_client_register \
+  --ssh-host organic-machine.com \
+  --container element_matrix_chat-mas-1 \
+  --config-file /home/ubuntu/CodeProyects/element_matrix_chat/mas/config.yaml
+```
+
+Salida esperada (sync OK):
+```json
+{
+  "status": "ok",
+  "applied": true,
+  "clients_total": 6,
+  "clients_diff": ["synced client element-web", "synced client synapse-admin", "..."],
+  "stderr": ""
+}
+```
+
+Salida dry-run:
+```json
+{
+  "status": "dry-run",
+  "applied": false,
+  "clients_total": 42,
+  "clients_diff": ["clients:", "  - client_id: element-web", "    ..."],
+  "stderr": ""
+}
+```
+
+## Cuando usarla
+
+Usar despues de editar `mas/config.yaml` localmente y antes de hacer restart a Synapse con `msc3861` habilitado en `homeserver.yaml`. Ejecutar primero con `--dry-run` para verificar que los 6 clients OAuth (Element Web, Synapse-Admin, matrix_client_pc, matrix_client_android, matrix_admin_panel, Synapse-internal) estan correctamente definidos, luego sin `--dry-run` para aplicar el sync.
+
+## Gotchas
+
+- **`--prune` elimina clients no declarados en config**: el sync real usa `--prune`, lo que borra cualquier client OAuth que exista en MAS pero no este en el `config.yaml`. Verificar con `--dry-run` antes de aplicar en produccion.
+- **Requiere `jq` en el host local**: el JSON output se construye con `jq`. Si no esta instalado, la funcion falla con error claro antes de conectar al VPS.
+- **`mas-cli` debe estar en el container**: la funcion asume que `mas-cli` esta en el PATH dentro del container MAS. Si el container usa una imagen diferente, verificar con `docker exec <container> mas-cli --version`.
+- **Config dentro del container siempre en `/data/config.yaml`**: el `--config-file` apunta a la ruta en el VPS (para que el operador sepa que archivo editar), pero el comando dentro del container usa `/data/config.yaml` (el mount point estandar de MAS). Si el compose monta el archivo en otro path, ajustar la constante `container_config` en el script.
+- **SSH key debe estar en agent o `~/.ssh/config`**: la funcion usa `ssh <alias>` directamente. Si la key requiere passphrase, ejecutar `ssh-add` antes.
+- **Si `config.yaml` es invalido, sync aborta sin tocar estado**: el paso 1 (`mas-cli config check`) detecta errores de sintaxis YAML antes de intentar sync. El estado de MAS no se modifica si la config tiene errores.
+- **Idempotente**: re-ejecutar con la misma config no genera cambios en MAS (mas-cli detecta que el estado ya coincide).

bash/functions/infra/mas_client_register.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# mas_client_register — Registra/sincroniza clientes OAuth en Matrix Authentication Service (MAS)
+# via mas-cli config sync ejecutado en container Docker remoto a traves de SSH.
+set -euo pipefail
+
+mas_client_register() {
+    local ssh_host=""
+    local container=""
+    local config_file=""
+    local dry_run=false
+
+    # Parse args
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ssh-host)
+                ssh_host="$2"
+                shift 2
+                ;;
+            --container)
+                container="$2"
+                shift 2
+                ;;
+            --config-file)
+                config_file="$2"
+                shift 2
+                ;;
+            --dry-run)
+                dry_run=true
+                shift
+                ;;
+            --help|-h)
+                cat >&2 <<'USAGE'
+mas_client_register - Sincroniza clientes OAuth en MAS via mas-cli config sync
+
+Usage:
+  mas_client_register --ssh-host <host> --container <name> --config-file <path> [--dry-run]
+
+Options:
+  --ssh-host     Alias SSH del VPS (ej. organic-machine.com)
+  --container    Nombre del container MAS (ej. element_matrix_chat-mas-1)
+  --config-file  Ruta en el VPS al mas/config.yaml (ej. /home/ubuntu/project/mas/config.yaml)
+  --dry-run      Solo valida config y muestra diff, sin aplicar cambios
+
+Output: JSON en stdout con status, applied, clients_total, clients_diff, stderr
+USAGE
+                # emit minimal valid JSON so callers that parse stdout don't break
+                echo '{"status":"help","applied":false,"clients_total":0,"clients_diff":[],"stderr":""}'
+                return 0
+                ;;
+            *)
+                echo "mas_client_register: argumento desconocido: $1" >&2
+                return 1
+                ;;
+        esac
+    done
+
+    # Validar argumentos obligatorios
+    local errors=()
+    [[ -z "$ssh_host"    ]] && errors+=("--ssh-host es obligatorio")
+    [[ -z "$container"   ]] && errors+=("--container es obligatorio")
+    [[ -z "$config_file" ]] && errors+=("--config-file es obligatorio")
+
+    if [[ ${#errors[@]} -gt 0 ]]; then
+        for err in "${errors[@]}"; do
+            echo "ERROR: $err" >&2
+        done
+        echo '{"status":"error","applied":false,"clients_total":0,"clients_diff":[],"stderr":"missing required arguments"}'
+        return 1
+    fi
+
+    # Verificar dependencias locales
+    if ! command -v jq &>/dev/null; then
+        echo "ERROR: jq no encontrado en el host local. Instalar: apt install jq / brew install jq" >&2
+        echo '{"status":"error","applied":false,"clients_total":0,"clients_diff":[],"stderr":"jq not found on local host"}'
+        return 1
+    fi
+
+    echo "mas_client_register: ssh-host=$ssh_host container=$container dry-run=$dry_run" >&2
+
+    # La ruta de config dentro del container siempre es /data/config.yaml (mount convention de MAS)
+    local container_config="/data/config.yaml"
+
+    # ---- PASO 1: Verificar sintaxis YAML con mas-cli config check ----
+    echo "mas_client_register: verificando sintaxis de config con mas-cli config check..." >&2
+    local check_stdout check_stderr check_exit
+    check_stdout=$(ssh "$ssh_host" \
+        "docker exec ${container} mas-cli config check --config ${container_config}" 2>/tmp/mas_check_stderr_$$ || true)
+    check_exit=$?
+    check_stderr=$(cat /tmp/mas_check_stderr_$$ 2>/dev/null || true)
+    rm -f /tmp/mas_check_stderr_$$
+
+    if [[ $check_exit -ne 0 ]]; then
+        echo "mas_client_register: config check falló (exit=$check_exit)" >&2
+        echo "$check_stderr" >&2
+        local escaped_stderr
+        escaped_stderr=$(printf '%s' "${check_stderr}" | jq -Rs '.')
+        echo "{\"status\":\"error\",\"applied\":false,\"clients_total\":0,\"clients_diff\":[],\"stderr\":${escaped_stderr}}"
+        return 1
+    fi
+
+    echo "mas_client_register: config check OK" >&2
+
+    # ---- PASO 2: dry-run o sync ----
+    if [[ "$dry_run" == "true" ]]; then
+        # Ejecutar mas-cli config dump para mostrar el estado actual y lo que se aplicaria
+        echo "mas_client_register: modo dry-run — ejecutando mas-cli config dump..." >&2
+        local dump_stdout dump_stderr dump_exit
+        dump_stdout=$(ssh "$ssh_host" \
+            "docker exec ${container} mas-cli config dump --config ${container_config}" 2>/tmp/mas_dump_stderr_$$ || true)
+        dump_exit=$?
+        dump_stderr=$(cat /tmp/mas_dump_stderr_$$ 2>/dev/null || true)
+        rm -f /tmp/mas_dump_stderr_$$
+
+        if [[ $dump_exit -ne 0 ]]; then
+            echo "mas_client_register: config dump falló (exit=$dump_exit)" >&2
+            echo "$dump_stderr" >&2
+            local escaped_stderr
+            escaped_stderr=$(printf '%s' "${dump_stderr}" | jq -Rs '.')
+            echo "{\"status\":\"error\",\"applied\":false,\"clients_total\":0,\"clients_diff\":[],\"stderr\":${escaped_stderr}}"
+            return 1
+        fi
+
+        # Extraer listado de clients del dump (buscar lineas con client_id o type: client)
+        local clients_diff_raw
+        clients_diff_raw=$(printf '%s\n' "$dump_stdout" | grep -E "client_id:|client_name:" | \
+            sed 's/^[[:space:]]*//' | head -50 || true)
+
+        local diff_json
+        diff_json=$(printf '%s\n' "$dump_stdout" | jq -Rs 'split("\n") | map(select(length > 0)) | map(ltrimstr("  "))' 2>/dev/null \
+            || echo '["(jq parse error — ver stderr)"]')
+
+        local escaped_dump_stderr
+        escaped_dump_stderr=$(printf '%s' "${dump_stderr}" | jq -Rs '.')
+
+        echo "mas_client_register: dry-run completado. dump lines=$(echo "$dump_stdout" | wc -l)" >&2
+
+        jq -n \
+            --argjson diff "$diff_json" \
+            --argjson stderr_str "$escaped_dump_stderr" \
+            '{
+                status: "dry-run",
+                applied: false,
+                clients_total: ($diff | length),
+                clients_diff: $diff,
+                stderr: $stderr_str
+            }'
+        return 0
+    fi
+
+    # ---- PASO 3: sync real ----
+    echo "mas_client_register: ejecutando mas-cli config sync --prune..." >&2
+    local sync_stdout sync_stderr sync_exit
+    sync_stdout=$(ssh "$ssh_host" \
+        "docker exec ${container} mas-cli config sync --config ${container_config} --prune" \
+        2>/tmp/mas_sync_stderr_$$ || true)
+    sync_exit=$?
+    sync_stderr=$(cat /tmp/mas_sync_stderr_$$ 2>/dev/null || true)
+    rm -f /tmp/mas_sync_stderr_$$
+
+    echo "mas_client_register: sync exit=$sync_exit" >&2
+    if [[ -n "$sync_stderr" ]]; then
+        echo "mas_client_register stderr: $sync_stderr" >&2
+    fi
+
+    if [[ $sync_exit -ne 0 ]]; then
+        local escaped_stderr
+        escaped_stderr=$(printf '%s' "${sync_stderr}" | jq -Rs '.')
+        echo "{\"status\":\"error\",\"applied\":false,\"clients_total\":0,\"clients_diff\":[],\"stderr\":${escaped_stderr}}"
+        return 1
+    fi
+
+    # Parsear output del sync para extraer lineas con cambios aplicados
+    local diff_lines
+    diff_lines=$(printf '%s\n' "$sync_stdout" | grep -E "^\s*(created|updated|deleted|unchanged|synced)" || true)
+
+    local diff_json
+    diff_json=$(printf '%s\n' "$sync_stdout" | jq -Rs 'split("\n") | map(select(length > 0))' 2>/dev/null \
+        || echo '[]')
+
+    local clients_count
+    clients_count=$(printf '%s\n' "$sync_stdout" | grep -cE "client" 2>/dev/null || echo 0)
+
+    local escaped_sync_stderr
+    escaped_sync_stderr=$(printf '%s' "${sync_stderr}" | jq -Rs '.')
+
+    echo "mas_client_register: sync completado con exito" >&2
+
+    jq -n \
+        --argjson diff "$diff_json" \
+        --argjson total "$clients_count" \
+        --argjson stderr_str "$escaped_sync_stderr" \
+        '{
+            status: "ok",
+            applied: true,
+            clients_total: $total,
+            clients_diff: $diff,
+            stderr: $stderr_str
+        }'
+}
+
+# Ejecutar si se llama directamente (no sourced)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    mas_client_register "$@"
+fi

bash/functions/infra/mas_client_register_test.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Tests para mas_client_register
+# No requiere SSH real — prueba paths locales (arg validation, --help, JSON output)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+PASS=0
+FAIL=0
+
+assert_contains() {
+    local test_name="$1" needle="$2" haystack="$3"
+    if echo "$haystack" | grep -qF "$needle"; then
+        echo "PASS: $test_name"
+        ((PASS++))
+    else
+        echo "FAIL: $test_name — expected to contain '$needle', got: $haystack"
+        ((FAIL++))
+    fi
+}
+
+assert_json_parseable() {
+    local test_name="$1" json="$2"
+    if command -v jq &>/dev/null; then
+        if echo "$json" | jq . >/dev/null 2>&1; then
+            echo "PASS: $test_name"
+            ((PASS++))
+        else
+            echo "FAIL: $test_name — output no es JSON valido: $json"
+            ((FAIL++))
+        fi
+    else
+        if [[ "$json" == \{* ]]; then
+            echo "PASS: $test_name (jq no disponible, verificacion basica OK)"
+            ((PASS++))
+        else
+            echo "FAIL: $test_name — output no parece JSON: $json"
+            ((FAIL++))
+        fi
+    fi
+}
+
+# Test: help flag emite JSON parseable
+# Cada invocacion en subshell aislada para no contaminar el runner con set -e del script fuente
+bash "$SCRIPT_DIR/mas_client_register.sh" --help >/tmp/mas_test_help_$$ 2>/dev/null || true
+output_help=$(cat /tmp/mas_test_help_$$ 2>/dev/null || true)
+rm -f /tmp/mas_test_help_$$
+assert_json_parseable "help flag emite JSON parseable" "$output_help"
+
+# Test: args faltantes retornan JSON de error sin ssh
+bash "$SCRIPT_DIR/mas_client_register.sh" >/tmp/mas_test_noargs_$$ 2>/dev/null || true
+output_noargs=$(cat /tmp/mas_test_noargs_$$ 2>/dev/null || true)
+rm -f /tmp/mas_test_noargs_$$
+assert_json_parseable "args faltantes retornan JSON de error sin ssh" "$output_noargs"
+assert_contains "args faltantes contienen status error" '"status":"error"' "$output_noargs"
+
+# Test: jq disponible en host local
+if command -v jq &>/dev/null; then
+    echo "PASS: jq disponible en host local"
+    ((PASS++))
+else
+    echo "FAIL: jq disponible en host local — instalar: apt install jq"
+    ((FAIL++))
+fi
+
+echo "---"
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]] || exit 1

bash/functions/infra/mas_syn2mas_migration.md

@@ -0,0 +1,83 @@
+---
+name: mas_syn2mas_migration
+kind: function
+lang: bash
+domain: infra
+version: "0.1.0"
+purity: impure
+signature: "mas_syn2mas_migration --ssh-host <host> --mas-container <name> --synapse-config-path <path-on-host> --log-dir <local-path> [--max-conflicts N] [--apply]"
+description: "Migra usuarios Synapse a Matrix Authentication Service (MAS) via mas-cli syn2mas. Fuerza dry-run primero, archiva el log, aborta si los conflicts superan el threshold, y solo ejecuta la migracion real con --apply."
+tags: [matrix, mas, syn2mas, migration, mas-migration, infra, users, docker, ssh, matrix-mas]
+params:
+  - name: ssh-host
+    desc: "Alias SSH del VPS donde corren los containers (ej. organic-machine.com)"
+  - name: mas-container
+    desc: "Nombre del container Docker de MAS (ej. element_matrix_chat-mas-1)"
+  - name: synapse-config-path
+    desc: "Ruta en el VPS al homeserver.yaml de Synapse (ej. /home/ubuntu/CodeProyects/element_matrix_chat/synapse_data/homeserver.yaml). El container debe tener el archivo accesible en /data/homeserver.yaml via volume mount."
+  - name: log-dir
+    desc: "Directorio local donde archivar logs dry-run y apply. Se crea con chmod 0700 y los logs con 0600 (contienen userIDs)."
+  - name: max-conflicts
+    desc: "Tope de conflictos detectados en dry-run. Si conflicts > max-conflicts, status=aborted exit 2. Default 0 (abortar ante cualquier conflict)."
+  - name: apply
+    desc: "Flag booleano. Sin --apply: solo dry-run (status=ok, sin cambios). Con --apply: ejecuta la migracion real tras pasar el threshold."
+output: "JSON en stdout: {\"status\":\"ok|aborted|error\",\"dry_run_log\":\"path\",\"apply_log\":\"path|null\",\"conflicts\":N,\"users_migrated\":N,\"duration_s\":N}. Exit 0=ok, 1=error, 2=aborted por conflicts."
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: true
+tests:
+  - "aborta con error cuando faltan args obligatorios"
+  - "help no devuelve error"
+  - "argumento desconocido retorna exit 1"
+  - "max-conflicts invalido retorna exit 1"
+test_file_path: "bash/functions/infra/mas_syn2mas_migration_test.sh"
+file_path: "bash/functions/infra/mas_syn2mas_migration.sh"
+---
+
+## Ejemplo
+
+```bash
+# Paso 1: dry-run OBLIGATORIO (sin --apply — no modifica nada)
+mas_syn2mas_migration \
+  --ssh-host organic-machine.com \
+  --mas-container element_matrix_chat-mas-1 \
+  --synapse-config-path /home/ubuntu/CodeProyects/element_matrix_chat/synapse_data/homeserver.yaml \
+  --log-dir ~/matrix_migration_logs \
+  --max-conflicts 0
+
+# Salida esperada (si hay 0 conflicts):
+# {"status":"ok","dry_run_log":"/home/lucas/matrix_migration_logs/syn2mas_dryrun_1234567890.log","apply_log":null,"conflicts":0,"users_migrated":0,"duration_s":0}
+
+# Revisar el log antes de continuar:
+# cat ~/matrix_migration_logs/syn2mas_dryrun_*.log
+
+# Paso 2: tras revisar el log dry-run, aplicar la migracion real
+mas_syn2mas_migration \
+  --ssh-host organic-machine.com \
+  --mas-container element_matrix_chat-mas-1 \
+  --synapse-config-path /home/ubuntu/CodeProyects/element_matrix_chat/synapse_data/homeserver.yaml \
+  --log-dir ~/matrix_migration_logs \
+  --max-conflicts 0 \
+  --apply
+
+# Salida esperada tras migracion exitosa:
+# {"status":"ok","dry_run_log":"/home/lucas/matrix_migration_logs/syn2mas_dryrun_1234567890.log","apply_log":"/home/lucas/matrix_migration_logs/syn2mas_apply_1234567890.log","conflicts":0,"users_migrated":42,"duration_s":15}
+```
+
+## Cuando usarla
+
+Usar en el paso 4 de la migracion del issue 0162 (Synapse a MAS auth), tras activar MSC3861 en `homeserver.yaml` y verificar que MAS esta corriendo con `syn2mas: true` en su config. NUNCA ejecutar antes de activar MSC3861 — sin ese flag activo, `syn2mas` no puede mapear usuarios a las tablas MAS y la migracion resultara en estado inconsistente.
+
+## Gotchas
+
+- **Dry-run NO modifica nada** — siempre ejecutar primero sin `--apply` y revisar el log manualmente antes de aplicar.
+- Si el dry-run detecta usuarios con **guest accounts**, **application services** (bots), o **passwords externos** (LDAP/OIDC), revisar manualmente el log antes de aplicar — estos casos pueden requerir steps adicionales documentados en el issue 0162.
+- **Backup postgres pre-migracion NO esta cubierto** por esta funcion. El operador es responsable de hacer `pg_dump` de la DB de Synapse antes de ejecutar con `--apply`. Ver issue 0162 paso 1.
+- Si la migracion real falla **a mitad**, MAS puede quedar en estado inconsistente con usuarios parcialmente migrados. El rollback consiste en restaurar el backup postgres de Synapse + revertir `homeserver.yaml` a la configuracion pre-MSC3861.
+- Los logs archivados en `--log-dir` **incluyen userIDs** (datos personales). Se crean con permisos `0600` (solo propietario puede leer). Mantener el directorio con `chmod 0700`. No subir los logs a repos publicos.
+- El comando `mas-cli syn2mas` en el container asume que `homeserver.yaml` esta montado en `/data/homeserver.yaml`. Si el volume mount del container usa otra ruta, el comando fallara con "file not found". Verificar con `docker inspect <container> | jq '.[].Mounts'`.
+- La postcondicion compara el count de usuarios MAS con una segunda ejecucion de dry-run para obtener el count esperado. Si el conteo no esta disponible (salida inesperada de mas-cli), la funcion emite `status=ok` con `users_migrated` del count real de MAS — no aborta por este motivo para evitar falsos negativos.

bash/functions/infra/mas_syn2mas_migration.sh

@@ -0,0 +1,325 @@
+#!/usr/bin/env bash
+# mas_syn2mas_migration — Migra usuarios Synapse a MAS via mas-cli syn2mas.
+# Fuerza dry-run primero, archiva el log, aborta si conflicts > threshold,
+# y solo ejecuta la migracion real cuando se pasa --apply.
+#
+# Usage:
+#   mas_syn2mas_migration --ssh-host <host> --mas-container <name> \
+#       --synapse-config-path <path-on-host> --log-dir <local-path> \
+#       [--max-conflicts N] [--apply]
+#
+# Output: JSON en stdout con status, dry_run_log, apply_log, conflicts, users_migrated, duration_s
+
+set -euo pipefail
+
+mas_syn2mas_migration() {
+    local ssh_host=""
+    local mas_container=""
+    local synapse_config_path=""
+    local log_dir=""
+    local max_conflicts=0
+    local do_apply=false
+
+    # ---- Parse args ----
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ssh-host)
+                ssh_host="$2"
+                shift 2
+                ;;
+            --mas-container)
+                mas_container="$2"
+                shift 2
+                ;;
+            --synapse-config-path)
+                synapse_config_path="$2"
+                shift 2
+                ;;
+            --log-dir)
+                log_dir="$2"
+                shift 2
+                ;;
+            --max-conflicts)
+                max_conflicts="$2"
+                shift 2
+                ;;
+            --apply)
+                do_apply=true
+                shift
+                ;;
+            --help|-h)
+                cat >&2 <<'USAGE'
+mas_syn2mas_migration - Migra usuarios Synapse a Matrix Authentication Service (MAS)
+
+Usage:
+  mas_syn2mas_migration \
+    --ssh-host <host> \
+    --mas-container <name> \
+    --synapse-config-path <path-on-host> \
+    --log-dir <local-path> \
+    [--max-conflicts N] \
+    [--apply]
+
+Opciones:
+  --ssh-host              Alias SSH del VPS (ej. organic-machine.com)
+  --mas-container         Nombre del container MAS (ej. element_matrix_chat-mas-1)
+  --synapse-config-path   Ruta en el VPS al homeserver.yaml
+                          (ej. /home/ubuntu/CodeProyects/element_matrix_chat/synapse_data/homeserver.yaml)
+  --log-dir               Directorio local donde archivar logs dry-run y apply
+  --max-conflicts N       Tope de conflictos en dry-run antes de abortar (default 0)
+  --apply                 Ejecutar migracion real. Sin esta flag: solo dry-run.
+
+Comportamiento:
+  1. Siempre ejecuta dry-run primero y archiva el log.
+  2. Si conflicts > max-conflicts -> status=aborted, exit 2.
+  3. Sin --apply -> status=ok (dry-run completado), exit 0.
+  4. Con --apply -> ejecuta migracion real, archiva log, verifica postcondicion.
+
+Output JSON: {"status":"ok|aborted|error","dry_run_log":"path","apply_log":"path|null","conflicts":N,"users_migrated":N,"duration_s":N}
+USAGE
+                echo '{"status":"help","dry_run_log":"","apply_log":null,"conflicts":0,"users_migrated":0,"duration_s":0}'
+                return 0
+                ;;
+            *)
+                echo "mas_syn2mas_migration: argumento desconocido: $1" >&2
+                return 1
+                ;;
+        esac
+    done
+
+    # ---- Validar argumentos obligatorios ----
+    local errors=()
+    [[ -z "$ssh_host"             ]] && errors+=("--ssh-host es obligatorio")
+    [[ -z "$mas_container"        ]] && errors+=("--mas-container es obligatorio")
+    [[ -z "$synapse_config_path"  ]] && errors+=("--synapse-config-path es obligatorio")
+    [[ -z "$log_dir"              ]] && errors+=("--log-dir es obligatorio")
+
+    if [[ ${#errors[@]} -gt 0 ]]; then
+        for err in "${errors[@]}"; do
+            echo "ERROR: $err" >&2
+        done
+        echo '{"status":"error","dry_run_log":"","apply_log":null,"conflicts":-1,"users_migrated":0,"duration_s":0}'
+        return 1
+    fi
+
+    # Validar que max_conflicts es un entero no negativo
+    if ! [[ "$max_conflicts" =~ ^[0-9]+$ ]]; then
+        echo "ERROR: --max-conflicts debe ser un entero >= 0, recibido: $max_conflicts" >&2
+        echo '{"status":"error","dry_run_log":"","apply_log":null,"conflicts":-1,"users_migrated":0,"duration_s":0}'
+        return 1
+    fi
+
+    # ---- Dependencias locales ----
+    if ! command -v jq &>/dev/null; then
+        echo "ERROR: jq no encontrado. Instalar: apt install jq / brew install jq" >&2
+        echo '{"status":"error","dry_run_log":"","apply_log":null,"conflicts":-1,"users_migrated":0,"duration_s":0}'
+        return 1
+    fi
+
+    # ---- Crear log-dir con permisos restringidos ----
+    mkdir -p "$log_dir"
+    chmod 0700 "$log_dir"
+
+    local ts
+    ts=$(date +%s)
+
+    local dry_run_log="${log_dir}/syn2mas_dryrun_${ts}.log"
+    local apply_log_path="null"
+    local apply_log_file="${log_dir}/syn2mas_apply_${ts}.log"
+
+    # La ruta del homeserver.yaml dentro del container MAS se pasa como --synapse-config
+    # MAS monta el directorio del synapse bajo /data/ por convencion, pero la ruta real
+    # puede variar — usamos la ruta tal como existe en el host (montada via volume).
+    # El comando real esperado: docker exec <container> mas-cli syn2mas --synapse-config <path>
+    # donde <path> es la ruta tal como el container la ve (via volume mount).
+    # Asumimos que el VPS tiene el config accesible en la misma ruta dentro del container.
+    local container_config="/data/homeserver.yaml"
+
+    echo "mas_syn2mas_migration: ssh-host=${ssh_host} container=${mas_container} max-conflicts=${max_conflicts} apply=${do_apply}" >&2
+
+    # =========================================================================
+    # PASO 1: DRY-RUN obligatorio
+    # =========================================================================
+    echo "mas_syn2mas_migration: ejecutando dry-run..." >&2
+
+    local dry_exit=0
+    # Capturar stdout+stderr del dry-run en el log y tambien en variable para parsing
+    local dry_output
+    dry_output=$(ssh "$ssh_host" \
+        "docker exec '${mas_container}' mas-cli syn2mas \
+            --synapse-config '${container_config}' \
+            --dry-run" \
+        2>&1) || dry_exit=$?
+
+    # Archivar log con timestamp + header informativo
+    {
+        echo "# mas_syn2mas_migration dry-run"
+        echo "# ts=${ts} ssh-host=${ssh_host} container=${mas_container}"
+        echo "# synapse-config-path=${synapse_config_path}"
+        echo "# exit=${dry_exit}"
+        echo "# ---"
+        printf '%s\n' "$dry_output"
+    } > "$dry_run_log"
+    chmod 0600 "$dry_run_log"
+
+    echo "mas_syn2mas_migration: dry-run exit=${dry_exit}, log=${dry_run_log}" >&2
+
+    if [[ $dry_exit -ne 0 ]]; then
+        # Si el comando SSH falla completamente (no es fallo de syn2mas sino de conectividad)
+        echo "mas_syn2mas_migration: ERROR — dry-run falló con exit ${dry_exit}" >&2
+        local escaped_out
+        escaped_out=$(printf '%s' "${dry_output}" | jq -Rs '.')
+        local dry_run_log_json
+        dry_run_log_json=$(printf '%s' "$dry_run_log" | jq -Rs '.')
+        echo "{\"status\":\"error\",\"dry_run_log\":${dry_run_log_json},\"apply_log\":null,\"conflicts\":-1,\"users_migrated\":0,\"duration_s\":0}"
+        return 1
+    fi
+
+    # =========================================================================
+    # PASO 2: Parsear conflicts del dry-run
+    # =========================================================================
+    # Regex sobre lineas tipo:
+    #   "Conflict:", "Skipping:", "Error processing user", "conflict"
+    # También contamos líneas que indiquen usuarios problemáticos.
+    local conflicts=0
+    local conflict_lines
+    conflict_lines=$(printf '%s\n' "$dry_output" | \
+        grep -ciE '(conflict|skipping|error processing user|cannot migrate|already exists)' 2>/dev/null || true)
+
+    # grep -c devuelve string; convertir a int defensivamente
+    if [[ "$conflict_lines" =~ ^[0-9]+$ ]]; then
+        conflicts=$conflict_lines
+    else
+        # Parser falló de forma inesperada — abortar defensivamente
+        echo "mas_syn2mas_migration: ERROR — no se pudo parsear el conteo de conflicts del dry-run (parser defensivo)" >&2
+        local dry_run_log_json
+        dry_run_log_json=$(printf '%s' "$dry_run_log" | jq -Rs '.')
+        echo "{\"status\":\"error\",\"dry_run_log\":${dry_run_log_json},\"apply_log\":null,\"conflicts\":-1,\"users_migrated\":0,\"duration_s\":0}"
+        return 1
+    fi
+
+    echo "mas_syn2mas_migration: conflicts detectados en dry-run: ${conflicts} (max permitido: ${max_conflicts})" >&2
+
+    # =========================================================================
+    # PASO 3: Verificar threshold de conflicts
+    # =========================================================================
+    if [[ $conflicts -gt $max_conflicts ]]; then
+        echo "mas_syn2mas_migration: ABORTADO — conflicts (${conflicts}) > max-conflicts (${max_conflicts})" >&2
+        echo "Revisar: ${dry_run_log}" >&2
+        local dry_run_log_json
+        dry_run_log_json=$(printf '%s' "$dry_run_log" | jq -Rs '.')
+        echo "{\"status\":\"aborted\",\"dry_run_log\":${dry_run_log_json},\"apply_log\":null,\"conflicts\":${conflicts},\"users_migrated\":0,\"duration_s\":0}"
+        return 2
+    fi
+
+    # =========================================================================
+    # PASO 4: Si no --apply, terminar aqui con status=ok (dry-run completado)
+    # =========================================================================
+    if [[ "$do_apply" == "false" ]]; then
+        echo "mas_syn2mas_migration: dry-run completado (${conflicts} conflicts). Revisar log y re-ejecutar con --apply." >&2
+        local dry_run_log_json
+        dry_run_log_json=$(printf '%s' "$dry_run_log" | jq -Rs '.')
+        echo "{\"status\":\"ok\",\"dry_run_log\":${dry_run_log_json},\"apply_log\":null,\"conflicts\":${conflicts},\"users_migrated\":0,\"duration_s\":0}"
+        return 0
+    fi
+
+    # =========================================================================
+    # PASO 5: Migracion REAL (--apply)
+    # =========================================================================
+    echo "mas_syn2mas_migration: ejecutando migracion REAL..." >&2
+    local apply_start
+    apply_start=$(date +%s)
+
+    local apply_exit=0
+    local apply_output
+    apply_output=$(ssh "$ssh_host" \
+        "docker exec '${mas_container}' mas-cli syn2mas \
+            --synapse-config '${container_config}'" \
+        2>&1) || apply_exit=$?
+
+    local apply_end
+    apply_end=$(date +%s)
+    local duration_s=$(( apply_end - apply_start ))
+
+    # Archivar log de apply
+    {
+        echo "# mas_syn2mas_migration apply"
+        echo "# ts=${ts} ssh-host=${ssh_host} container=${mas_container}"
+        echo "# synapse-config-path=${synapse_config_path}"
+        echo "# exit=${apply_exit} duration_s=${duration_s}"
+        echo "# ---"
+        printf '%s\n' "$apply_output"
+    } > "$apply_log_file"
+    chmod 0600 "$apply_log_file"
+
+    apply_log_path="$apply_log_file"
+    echo "mas_syn2mas_migration: apply exit=${apply_exit}, duration=${duration_s}s, log=${apply_log_file}" >&2
+
+    if [[ $apply_exit -ne 0 ]]; then
+        echo "mas_syn2mas_migration: ERROR — migracion real falló con exit ${apply_exit}" >&2
+        local dry_run_log_json apply_log_json
+        dry_run_log_json=$(printf '%s' "$dry_run_log" | jq -Rs '.')
+        apply_log_json=$(printf '%s' "$apply_log_file" | jq -Rs '.')
+        echo "{\"status\":\"error\",\"dry_run_log\":${dry_run_log_json},\"apply_log\":${apply_log_json},\"conflicts\":${conflicts},\"users_migrated\":0,\"duration_s\":${duration_s}}"
+        return 1
+    fi
+
+    # =========================================================================
+    # PASO 6: Postcondicion — comparar usuarios en MAS vs Synapse
+    # =========================================================================
+    echo "mas_syn2mas_migration: verificando postcondicion (usuarios MAS vs Synapse)..." >&2
+
+    local mas_user_count=0
+    local synapse_user_count=0
+    local users_migrated=0
+    local post_status="ok"
+
+    # Contar usuarios en MAS via mas-cli admin user list
+    local mas_count_raw
+    mas_count_raw=$(ssh "$ssh_host" \
+        "docker exec '${mas_container}' mas-cli manage list-users --json 2>/dev/null | jq length" \
+        2>/dev/null || echo "0")
+
+    if [[ "$mas_count_raw" =~ ^[0-9]+$ ]]; then
+        mas_user_count=$mas_count_raw
+    else
+        echo "mas_syn2mas_migration: ADVERTENCIA — no se pudo obtener conteo de usuarios MAS (output: ${mas_count_raw})" >&2
+        post_status="ok"  # No abortar, solo advertir
+    fi
+
+    # Contar usuarios locales en Synapse via psql (excluyendo bots/AS)
+    # Intentamos obtener el count; si falla, continuamos sin abortar
+    local synapse_count_raw
+    synapse_count_raw=$(ssh "$ssh_host" \
+        "docker exec '${mas_container}' mas-cli syn2mas --synapse-config '${container_config}' --dry-run 2>&1 | grep -oE 'Found [0-9]+ users' | grep -oE '[0-9]+' | head -1" \
+        2>/dev/null || echo "0")
+
+    if [[ "$synapse_count_raw" =~ ^[0-9]+$ ]]; then
+        synapse_user_count=$synapse_count_raw
+    fi
+
+    users_migrated=$mas_user_count
+
+    # Si tenemos ambos counts y difieren significativamente, marcar como warning en log
+    if [[ $synapse_user_count -gt 0 && $mas_user_count -eq 0 ]]; then
+        echo "mas_syn2mas_migration: ADVERTENCIA — MAS reporta 0 usuarios pero Synapse tenia ${synapse_user_count}" >&2
+        post_status="error"
+    fi
+
+    echo "mas_syn2mas_migration: postcondicion: mas_users=${mas_user_count} synapse_users=${synapse_user_count} status=${post_status}" >&2
+
+    # =========================================================================
+    # PASO 7: Emitir JSON final
+    # =========================================================================
+    local dry_run_log_json apply_log_json
+    dry_run_log_json=$(printf '%s' "$dry_run_log" | jq -Rs '.')
+    apply_log_json=$(printf '%s' "$apply_log_file" | jq -Rs '.')
+
+    echo "{\"status\":\"${post_status}\",\"dry_run_log\":${dry_run_log_json},\"apply_log\":${apply_log_json},\"conflicts\":${conflicts},\"users_migrated\":${users_migrated},\"duration_s\":${duration_s}}"
+    return 0
+}
+
+# Ejecutar si se llama directamente (no sourced)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    mas_syn2mas_migration "$@"
+fi

bash/functions/infra/mas_syn2mas_migration_test.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Tests para mas_syn2mas_migration
+# Verifica arg parsing sin conectar al VPS real.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/mas_syn2mas_migration.sh"
+
+PASS=0
+FAIL=0
+
+assert_exit() {
+    local test_name="$1" expected_exit="$2"
+    shift 2
+    local actual_exit=0
+    set +e
+    "$@" >/dev/null 2>&1
+    actual_exit=$?
+    set -e
+    if [[ "$actual_exit" == "$expected_exit" ]]; then
+        echo "PASS: $test_name"
+        ((PASS++)) || true
+    else
+        echo "FAIL: $test_name — expected exit $expected_exit, got $actual_exit"
+        ((FAIL++)) || true
+    fi
+}
+
+assert_stdout_contains() {
+    local test_name="$1" needle="$2"
+    shift 2
+    local output actual_exit=0
+    set +e
+    output=$("$@" 2>/dev/null)
+    actual_exit=$?
+    set -e
+    if echo "$output" | grep -q "$needle"; then
+        echo "PASS: $test_name"
+        ((PASS++)) || true
+    else
+        echo "FAIL: $test_name — expected stdout to contain '$needle', got: $output"
+        ((FAIL++)) || true
+    fi
+}
+
+# Test: aborta con error cuando faltan args obligatorios
+assert_exit "aborta con error cuando faltan args obligatorios" 1 \
+    mas_syn2mas_migration
+
+# Test: help no devuelve error
+assert_exit "help no devuelve error" 0 \
+    mas_syn2mas_migration --help
+
+# Test: argumento desconocido retorna exit 1
+assert_exit "argumento desconocido retorna exit 1" 1 \
+    mas_syn2mas_migration --unknown-flag
+
+# Test: max-conflicts invalido retorna exit 1
+assert_exit "max-conflicts invalido retorna exit 1" 1 \
+    mas_syn2mas_migration \
+        --ssh-host fake-host \
+        --mas-container fake-container \
+        --synapse-config-path /fake/homeserver.yaml \
+        --log-dir "/tmp/test_mas_migration_$$" \
+        --max-conflicts "not-a-number"
+
+# Test: help emite JSON valido con status=help
+assert_stdout_contains "help emite JSON con status help" '"status":"help"' \
+    mas_syn2mas_migration --help
+
+# Test: falta --ssh-host emite JSON con status=error
+assert_stdout_contains "falta ssh-host emite JSON error" '"status":"error"' \
+    mas_syn2mas_migration \
+        --mas-container fake-container \
+        --synapse-config-path /fake/homeserver.yaml \
+        --log-dir "/tmp/test_mas_migration_$$"
+
+# Test: falta --log-dir emite JSON con status=error
+assert_stdout_contains "falta log-dir emite JSON error" '"status":"error"' \
+    mas_syn2mas_migration \
+        --ssh-host fake-host \
+        --mas-container fake-container \
+        --synapse-config-path /fake/homeserver.yaml
+
+# Limpieza
+rm -rf "/tmp/test_mas_migration_$$" 2>/dev/null || true
+
+echo "---"
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]] || exit 1