Plugins

Esta página es para el administrador: cómo instalar un plugin o un tema, qué aceptas al hacerlo y qué le deja tocar el servidor en tu equipo. Todo pasa en Administración → Plugins; las páginas para quienes escriben plugins están listadas al final.

Un plugin añade a Evey lo que no hace por sí mismo: una sección en la página de inicio, una capa encima del reproductor, una fuente de metadatos, un tema. Cada plugin es un proceso aparte que se comunica con el servidor a través de un socket local, aislado en un sandbox y limitado a los permisos que declara su manifiesto. Su interfaz, si tiene una, funciona en un marco aislado de la página.

Sin plugins.

Con el plugin de ejemplo del tiempo: una sección arriba, dibujada en su propio marco.

Instalar un plugin

1. En Administración → Plugins, abre Instalar plugin y elige el Archivo de plugin (.zip). Si el autor proporciona una firma, añádela en Archivo de firma (.zip.sig, opcional). La pestaña Desde URL instala a partir de un enlace; añade #sha256:<hash> a la URL para que se compruebe la descarga.
2. Vista previa e instalar analiza el paquete sin instalarlo. La vista previa muestra los Permisos y las Capacidades que pide el plugin, el resultado del Análisis estático y, cuando se dio una firma, el veredicto de Firma con el editor. Los huecos (slots) y los servidores se muestran en la actualización y en el Panel de seguridad.
3. Lee esa lista como un contrato: es lo único que el plugin podrá hacer. Confirma y el plugin arranca.

Administración → Plugins: los entornos de ejecución disponibles, los límites de recursos y una tarjeta por plugin (interfaz en inglés).

Un paquete cuyo análisis encuentra un patrón crítico se rechaza, respondas lo que respondas. Los avisos se muestran y la decisión es tuya. El lenguaje del plugin tiene que estar entre los Entornos de ejecución disponibles del servidor: la imagen por defecto trae Python, Node.js, PHP, Ruby y Lua, la imagen -nodejs conserva Python y Node.js y la imagen -lean solo Python.

Plugins firmados

El autor de un plugin puede firmar el ZIP con cosign; su clave pública viaja dentro del paquete. Evey comprueba la firma por sí mismo (sin binario cosign) y muestra Firmado por cuando la clave está en tu lista de Editores de confianza, Firmado, clave desconocida con su huella en caso contrario (un clic confía en ella), Sin firma o No válida. Una actualización que cambia de clave, o que abandona la firma, espera tu aceptación explícita. La política decide el resto:

EVEY_PLUGINS_COSIGN_POLICY=warn      # off | warn (por defecto) | enforce

Con warn, el veredicto se muestra y no se bloquea nada; con enforce, solo se instalan los editores de confianza. Para los autores: consulta Firma tu plugin.

Actualizar un plugin

En la tarjeta del plugin, Actualizar desde origen… acepta el nuevo ZIP (una ruta o una URL) y muestra la misma vista previa. Una actualización tiene que llevar una versión más alta que la instalada. Cuando pide nuevos permisos, capacidades, slots o servidores, la vista previa dice Esta actualización solicita nuevos permisos y muestra la diferencia: no se aplica nada hasta que eliges Aprobar e instalar. El paquete analizado es el paquete instalado: su hash se vuelve a comprobar cuando se aplica la actualización.

Gestionar los plugins instalados

Cada tarjeta muestra el estado del plugin (Activado o Desactivado) y ofrece:

Acción	Qué hace
Activado / Desactivado	Arranca o detiene el proceso del plugin. Un plugin desactivado conserva sus archivos y su configuración.
Configuración	Los ajustes que declara el plugin (una clave de API, una ciudad, una unidad...). Los campos secretos se muestran ocultos y nunca se devuelven al navegador.
Registros	Las últimas líneas que el plugin escribió a través del servidor.
Desinstalar	Elimina el proceso, los archivos y los datos guardados del plugin.

Límites de recursos, arriba de la página, pone un tope a cada proceso de plugin. Los valores del panel son los valores por defecto; la variable de entorno los define mientras el panel no se haya guardado nunca.

Campo	Por defecto	Variable de entorno
Memoria máx. (MiB)	256	EVEY_PLUGINS_MEMORY_MB
Procesos máx.	64	EVEY_PLUGINS_PIDS_MAX
Disco máx. (MiB)	100	EVEY_PLUGINS_DISK_MAX_MB
Nice de CPU (0-19)	10	EVEY_PLUGINS_CPU_NICE
Modo de sandbox	auto	EVEY_PLUGINS_SANDBOX_MODE

La memoria, los procesos y el disco se aplican en la siguiente revisión del monitor, que detiene un plugin que los supere; la prioridad de CPU y el modo de sandbox se aplican a los plugins que arranquen después. 0 restablece el valor por defecto para la memoria y los procesos; solo el límite de disco trata 0 como desactivado.

El Panel de seguridad guarda, para cada plugin, lo que encontró el análisis, el resultado de la firma y el último error. Su línea Sandbox del host muestra el modo de sandbox realmente activo en esta máquina: si dice basic, el equipo no ofrece aislamiento del sistema de archivos por rutas, y Configurar el sandbox de plugins explica qué cambiar.

Los plugins están activados por defecto. EVEY_PLUGINS_ENABLED=false desactiva todo el sistema de plugins.

Lo que un plugin puede hacer en tu equipo

Diga lo que diga su manifiesto, un plugin:

• ve su propia carpeta, no los datos del servidor ni los archivos de medios;
• no tiene acceso directo a la red: un plugin con el permiso network solo llega a los servidores que declaró, a través del servidor de Evey, con GET y HEAD;
• no puede lanzar procesos hijos salvo que declare subprocess;
• funciona con los límites de recursos de arriba y, si el equipo lo permite, con un usuario aparte.

Su interfaz queda limitada a los slots que declara el manifiesto: una sección o la zona destacada de la página de inicio, un panel lateral en una biblioteca o en una página de detalle, una capa encima del reproductor, los ajustes de apariencia, la parte de abajo de la barra lateral de navegación, o una entrada en el menú de administración que abre la página propia del plugin. Un plugin nunca puede dibujar en las pantallas de inicio de sesión, de configuración inicial, de seguridad ni en las pantallas de administración existentes. En su marco, no tiene acceso a la página, ni a tus cookies, ni a tu sesión: lo que lee del servidor pasa por un token de corta duración, limitado a los dos permisos que puede pedir (public para una vista segura de los títulos y carteles de los medios, prefs para las preferencias del usuario actual en su propio espacio de nombres).

Los permisos que puede pedir un plugin están listados en Permisos y slots. Cómo funciona el sandbox, y lo que todavía no puede impedir, está en Sandbox de plugins y modelo de amenazas.

El servidor controla con quién se comunica un plugin, no lo que envía

En cuanto un servidor está en la lista de un plugin, Evey no puede inspeccionar lo que el plugin le envía. Revisa un plugin de terceros antes de instalarlo, como harías con cualquier programa, y considera su lista de servidores como la lista de quienes pueden recibir los títulos de tu biblioteca.

Temas

Un tema es un paquete de tipo kind: theme sin proceso: una hoja de estilos y, opcionalmente, un script aislado en un marco oculto. Se instala desde el mismo cuadro Instalar plugin; la hoja de estilos se sanea al instalarla. Después, cada usuario lo elige en Ajustes → Apariencia → Tema. Lo que puede contener un tema se describe en Temas.

Escribir un plugin

Página	Contenido
Escribir un plugin	Un primer plugin paso a paso, el ciclo de instalación, la firma y la distribución. Empieza por aquí.
Referencia de la API de plugins	El manifiesto, las llamadas del backend y el almacén de datos, el puente evey.* de la interfaz.
Permisos y slots	Lo que puede declarar un manifiesto, lo que se comprueba al instalar, las reglas de las peticiones externas, los slots.
Temas	Cambiar el estilo de la interfaz con CSS y un script en un sandbox.
Webhooks y claves de API	Integrar Evey con otras herramientas sin escribir un plugin.