Panel web

El panel es una pequeña aplicación web que sirve el mismo plugin. No necesita hosting web ni base de datos, no carga nada de una CDN y no le hace ningún pedido a terceros: todos los archivos salen del plugin.

Ingresar #

• La dirección por defecto es http://127.0.0.1:8765/, que solo responde en la máquina del servidor. Mirá Llegar al panel para abrirlo desde otro lado.
• Ingresá con tu nombre de Minecraft y la contraseña que definiste en el juego con /chatshield password, o corré /chatshield panel en el juego para recibir un enlace de un solo uso que te hace ingresar directamente (vale 10 minutos y se usa una sola vez).
• Si el dueño activa el ingreso con la contraseña del juego, el staff también puede usar la contraseña del plugin de login del servidor (LoginSecurity o AuthMe).
• El panel habla inglés, español y español rioplatense; el idioma que elegís sigue a tu cuenta en otros navegadores. Tiene tema claro y oscuro, sigue a tu dispositivo por defecto y funciona en celulares.
• Las páginas se actualizan en tiempo real, y el tablero muestra quién más está viendo el panel.

Secciones y quién las ve #

Cada cuenta ve lo que permiten sus grupos (access.groups en config.yml) o sus permisos chatshield.panel.*. Las secciones fuera de ese alcance no aparecen en el menú.

El alcance settings equivale a acceso a la consola, porque puede editar los comandos automáticos. Dáselo solo a los dueños. Los valores secretos (contraseña SMTP, clave de IA, clave de licencia) nunca se mandan al navegador.

Llegar al panel #

Solo local (por defecto) #

panel:
  bind: 127.0.0.1
  port: 8765

El panel solo responde en la máquina del servidor. Para abrirlo desde tu computadora, usá un túnel SSH: ssh -L 8765:127.0.0.1:8765 user@your-server, y después entrá a http://127.0.0.1:8765/ con el navegador.

Detrás de un proxy inverso (recomendado) #

Poné nginx, Caddy u otro proxy inverso con HTTPS delante del plugin. Así el panel tiene HTTPS, cookies seguras y la dirección real del visitante para los límites de intentos y el registro de auditoría. Dejá bind: 127.0.0.1, para que al plugin solo se llegue a través del proxy, y confiá en los encabezados reenviados del proxy:

panel:
  bind: 127.0.0.1
  port: 8765
  base-path: ""                         # "/chatshield" si el panel vive bajo una ruta
  public-url: "https://panel.example.com"
  behind-proxy: { enabled: true, trusted-proxies: ["127.0.0.1"] }

Las actualizaciones en vivo usan Server-Sent Events, así que el proxy no tiene que almacenar en búfer las respuestas del panel. Para un subdominio como https://panel.example.com/:

server {
    listen 443 ssl;
    server_name panel.example.com;
    # ssl_certificate ...; ssl_certificate_key ...;

    location / {
        proxy_pass http://127.0.0.1:8765;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;          # actualizaciones en vivo (Server-Sent Events)
        proxy_read_timeout 1h;
    }
}

panel.example.com {
    reverse_proxy 127.0.0.1:8765 {
        flush_interval -1
    }
}

Para una subruta como https://www.example.com/chatshield/, poné base-path: "/chatshield" y public-url: "https://www.example.com/chatshield", y reenviá la ruta sin cambios (en nginx, location /chatshield/ { proxy_pass http://127.0.0.1:8765; ... }, sin ninguna ruta después del puerto). Todas las direcciones que arma el panel son relativas, así que funciona bajo cualquier ruta.

HTTPS integrado #

El plugin también puede servir el panel por HTTPS (TLS 1.2 y 1.3) por su cuenta, con un keystore PKCS12 (.p12, .pfx) o JKS en plugins/ChatShield/:

panel:
  https:
    enabled: true
    keystore: "keystore.p12"
    password: ""        # o la variable de entorno CS_PANEL_KEYSTORE_PASSWORD
    alias: ""           # vacío = la primera clave del keystore

Un certificado y una clave en archivos PEM se pueden convertir en un keystore con openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out keystore.p12; la contraseña de exportación que elijas va en panel.https.password. A diferencia de un proxy inverso, el plugin no renueva certificados: cuando se renueve el tuyo, reemplazá el keystore y reiniciá el servidor. Los cambios en los ajustes de panel.https tienen efecto después de un reinicio o de /chatshield reload desde la consola o el juego.

Siempre que el panel escucha en una dirección que no es la de la máquina local, la consola avisa al arrancar. En ese caso, sigue siendo más seguro usar un proxy inverso que limite las conexiones lentas y repetidas.

En tu propio sitio web (Pro) #

Podés alojar los archivos del panel en tu propio sitio web (por ejemplo https://www.example.com/staff/) mientras la API se queda en el servidor de Minecraft:

1. Poné en panel.public-url la dirección en la que se llega al plugin (idealmente detrás de HTTPS) y agregá el origen de tu sitio web a panel.allowed-origins, por ejemplo ["https://www.example.com"].
2. En el panel, abrí Estado y descargá el paquete del panel para tu sitio web. Viene con la dirección de la API ya completada.
3. Descomprimilo donde tenga que vivir el panel en tu sitio, respetando la estructura de carpetas.
4. Servilo con una Content-Security-Policy que permita la API, por ejemplo default-src 'self'; connect-src 'self' https://mc.example.com:8765; img-src 'self' data:; frame-ancestors 'none'.

La copia alojada ingresa con un token que se guarda en el almacenamiento de sesión de la pestaña del navegador. En Free, el servidor rechaza este tipo de ingreso.

Ingresar con la contraseña del juego #

En un servidor donde los jugadores ya ingresan con LoginSecurity (3.x) o AuthMe Reloaded, el staff puede ingresar al panel con el mismo nombre y la misma contraseña, sin una contraseña aparte para el panel. Viene apagado por defecto y funciona en Free y en Pro:

panel:
  game-login:
    enabled: true
    provider: auto          # auto (LoginSecurity, después AuthMe) | loginsecurity | authme
    create-accounts: true   # el primer ingreso con la contraseña del juego crea la cuenta del panel

Aplicalo con /chatshield reload. El formulario de ingreso pasa a decir "Usá la misma contraseña con la que entrás al juego", y /chatshield status nombra el plugin de login en uso.

• Solo entran los jugadores cuyos grupos pueden usar el panel. Todos los demás reciben el mismo "Nombre o contraseña incorrectos" que con una contraseña equivocada, y cada intento cuenta para el límite de intentos de ingreso y para el bloqueo.
• El primer ingreso con la contraseña del juego crea la cuenta del panel, dentro del límite de 3 cuentas de Free. El jugador tiene que haber entrado al servidor al menos una vez desde que se instaló ChatShield.
• Usá HTTPS siempre que se pueda llegar al panel desde otras máquinas: son las contraseñas que los jugadores usan en el juego. La consola avisa cuando podrían viajar por la red sin cifrar.
• El panel no comprueba los códigos de doble factor de AuthMe. Si tu servidor le exige al staff el doble factor de AuthMe, dejá apagado el ingreso con la contraseña del juego y usá contraseñas del panel.
• Para quitar el acceso, sacá al jugador de los grupos permitidos o desactivá su cuenta del panel en la página Usuarios (Pro). Borrar la cuenta no alcanza mientras create-accounts esté activado.
• Cambiar la contraseña del juego no cierra las sesiones del panel que ya están abiertas. Cerralas desde la página Usuarios (Pro), o con /chatshield user setpassword <name> <password>, que cierra todas las sesiones de esa cuenta.

Skins de los jugadores #

La página de un jugador se abre con una imagen de su skin actual, que se lee del perfil de juego del jugador cuando entra. Funciona en servidores en modo online, en servidores en modo offline con SkinsRestorer y para jugadores de Bedrock a través de Geyser y Floodgate.

Para mostrarla, el servidor descarga cada imagen de skin del servidor de skins de Mojang, textures.minecraft.net, por HTTPS, y guarda las imágenes en plugins/ChatShield/skins/. Los navegadores reciben la imagen del plugin y nunca contactan a Mojang. Poné panel.skin-downloads: false cuando tu host bloquee el tráfico saliente o el servidor no deba contactar a Mojang: no se descarga nada, y la página muestra en su lugar una silueta neutra.

Atajos de teclado #

Apretá ? en el panel para ver la lista. Los atajos se desactivan mientras escribís en un campo.

Seguridad #

• Las contraseñas se guardan como hash con PBKDF2. Los ingresos tienen límites de intentos y bloqueo, y los ingresos y las acciones del staff se escriben en un registro de auditoría (plugins/ChatShield/logs/audit-<date>.log).
• Las sesiones usan cookies HttpOnly; SameSite=Strict (más Secure por HTTPS), y cada cambio lleva un token CSRF. /chatshield user setpassword cierra todas las sesiones de una cuenta; en Pro, los dueños también pueden cerrar sesiones desde la página Usuarios.
• Las páginas se sirven con una Content-Security-Policy estricta, X-Frame-Options: DENY y Referrer-Policy: no-referrer. Todo lo que viene de los jugadores se muestra como texto plano, nunca como HTML.
• El enlace de un solo uso de /chatshield panel se saca de la barra de direcciones antes de usarlo, así no queda en el historial del navegador.

Personalizar los archivos #

Cualquier archivo del panel se puede reemplazar poniendo un archivo con la misma ruta relativa en plugins/ChatShield/panel/ (por ejemplo panel/assets/logo.svg). Borrá tu copia para volver al archivo incluido después de una actualización.