fn_registry/docs/capabilities/matrix-mas.md

group, description, tags, functions

group	description	tags	functions
matrix-mas	Migración y operación de Synapse con Matrix Authentication Service (MAS). Cubre habilitación de MSC3861, verificación de login flows, parche .well-known OIDC, registro de clientes MAS y migración syn2mas.	matrix mas synapse migration	synapse_login_flows_check_go_infra synapse_msc3861_enable_go_infra wellknown_oidc_patch_go_infra mas_client_register_bash_infra mas_syn2mas_migration_bash_infra

Funciones

ID	Firma corta	Qué hace
synapse_login_flows_check_go_infra	SynapseLoginFlowsCheck(cfg) (result, error)	Polling de /_matrix/client/v3/login hasta confirmar SSO/MAS activo y password desactivado
synapse_msc3861_enable_go_infra	SynapseMsc3861Enable(cfg) (result, error)	Habilita MSC3861 en homeserver.yaml vía SSH y reinicia Synapse
wellknown_oidc_patch_go_infra	WellknownOidcPatch(cfg) (result, error)	Parchea .well-known/matrix/client para añadir el bloque m.authentication de MAS
mas_client_register_bash_infra	mas_client_register(ssh_host, container, config_file, dry_run)	Registra un cliente OAuth2 en MAS vía mas-cli manage register-client
mas_syn2mas_migration_bash_infra	mas_syn2mas_migration --ssh-host ... --mas-container ... --synapse-config-path ...	Ejecuta la migración syn2mas de usuarios y sesiones de Synapse a MAS

Ejemplo canónico — verificar post-migración (issue 0162, paso 6)

// 1. Habilitar MSC3861 en homeserver.yaml y reiniciar Synapse
resCfg := SynapseMsc3861Config{
    SSHHost:         "organic-machine",
    HomserverPath:   "/etc/synapse/homeserver.yaml",
    RestartCommand:  "systemctl restart matrix-synapse",
}
_, err := SynapseMsc3861Enable(resCfg)
if err != nil {
    log.Fatalf("enable MSC3861: %v", err)
}

// 2. Parchar .well-known con bloque m.authentication
patchCfg := WellknownOidcPatchConfig{
    WellknownPath: "/var/www/.well-known/matrix/client",
    IssuerURL:     "https://mas.organic-machine.com/",
}
_, err = WellknownOidcPatch(patchCfg)
if err != nil {
    log.Fatalf("well-known patch: %v", err)
}

// 3. Verificar que login flows ya no exponen m.login.password
checkCfg := SynapseLoginFlowsCheckConfig{
    HomeserverURL:     "https://matrix-af2f3d.organic-machine.com",
    ExpectedSsoIdpID:  "oidc-mas",
    MaxRetries:        10,
    RetryDelaySeconds: 3,
}
res, err := SynapseLoginFlowsCheck(checkCfg)
if err != nil {
    log.Fatalf("login flows check: %v\nlast response: %s", err, res.LastResponseJSON)
}
fmt.Printf("MAS confirmed after %d attempt(s). SSO: %v, Password: %v\n",
    res.AttemptsUsed, res.SsoPresent, res.PasswordEnabled)

Fronteras

• Este grupo cubre la migración y validación de Synapse→MAS. No cubre la configuración inicial de MAS ni la gestión de usuarios post-migración.
• Las funciones bash (mas_client_register, mas_syn2mas_migration) operan vía SSH sobre el host remoto — requieren acceso SSH configurado en ~/.ssh/config.
• Las funciones Go (synapse_login_flows_check, synapse_msc3861_enable, wellknown_oidc_patch) pueden correr localmente o en pipelines CI.

Prerequisitos

• Acceso SSH al host donde corre Synapse (alias en ~/.ssh/config).
• MAS desplegado y accesible antes de ejecutar la migración.
• ExpectedSsoIdpID verificado contra mas/config.yaml → clients[].id del homeserver Synapse.

Orden recomendado (issue 0162)

1. mas_client_register — registrar Synapse como cliente OAuth2 en MAS.
2. synapse_msc3861_enable — habilitar MSC3861 + reiniciar.
3. wellknown_oidc_patch — actualizar .well-known.
4. synapse_login_flows_check — confirmar convergencia post-restart.
5. mas_syn2mas_migration — migrar usuarios y sesiones existentes.