Plugins

Cette page s'adresse à l'administrateur : comment installer un plugin ou un thème, ce que vous acceptez en le faisant, et ce que le serveur lui permet de faire sur votre machine. Tout se passe dans Administration → Plugins ; les pages destinées aux auteurs de plugins sont listées à la fin.

Un plugin ajoute à Evey ce qu'il ne fait pas lui-même : une section sur la page d'accueil, une surcouche dans le lecteur, une source de métadonnées, un thème. Chaque plugin est un processus à part, qui communique avec le serveur par un socket local, confiné par une sandbox et limité aux permissions que déclare son manifeste. Son interface, quand il en a une, s'exécute dans un cadre isolé de la page.

Sans plugin.

Avec le plugin météo d'exemple : une section en haut, affichée dans son propre cadre.

Installer un plugin

1. Dans Administration → Plugins, ouvrez Installer un plugin et choisissez le Fichier plugin (.zip). Si l'auteur fournit une signature, ajoutez-la dans Fichier signature (.zip.sig, optionnel). L'onglet Depuis une URL installe à partir d'un lien ; ajoutez #sha256:<empreinte> à l'URL pour faire vérifier le téléchargement.
2. Aperçu et installation analyse le paquet sans l'installer. L'aperçu montre les Permissions et les Capacités que demande le plugin, le résultat de l'Analyse statique et, quand une signature a été fournie, le verdict Signature avec l'éditeur. Les emplacements et les hôtes sont montrés à la mise à jour et dans le Tableau de bord sécurité.
3. Lisez cette liste comme un contrat : ce sont les seules choses que le plugin pourra faire. Confirmez, et le plugin démarre.

Admin → Plugins : les environnements d'exécution disponibles, les limites de ressources, et une carte par plugin.

Un paquet dont l'analyse relève un motif critique est refusé, quelle que soit votre réponse. Les avertissements sont affichés et laissés à votre appréciation. Le langage du plugin doit figurer parmi les Environnements d'exécution disponibles du serveur : l'image par défaut embarque Python, Node.js, PHP, Ruby et Lua ; l'image -nodejs garde Python et Node.js et l'image -lean ne garde que Python.

Plugins signés

L'auteur d'un plugin peut signer le ZIP avec cosign ; sa clé publique voyage dans le paquet. Evey vérifie la signature seul (pas de binaire cosign) et affiche Signé par <éditeur> quand la clé est dans votre liste d'Éditeurs de confiance, Signé, clé inconnue avec son empreinte sinon (un clic lui fait confiance), Non signé ou Invalide. Une mise à jour qui change de clé, ou qui abandonne la signature, attend votre acceptation explicite. La politique décide du reste :

EVEY_PLUGINS_COSIGN_POLICY=warn      # off | warn (défaut) | enforce

Avec warn, le verdict est affiché et rien n'est bloqué ; avec enforce, seuls les éditeurs de confiance s'installent. Auteurs : voir Signer son plugin.

Mettre à jour un plugin

Sur la carte du plugin, Mettre à jour depuis la source… prend le nouveau ZIP (un chemin ou une URL) et affiche le même aperçu. Une mise à jour doit porter une version supérieure à celle installée. Quand elle demande de nouvelles permissions, capacités, emplacements ou hôtes, l'aperçu indique Cette mise à jour demande de nouvelles permissions et liste la différence : rien n'est appliqué tant que vous n'avez pas choisi Approuver et installer. Le paquet analysé est le paquet installé : son empreinte est vérifiée de nouveau au moment d'appliquer la mise à jour.

Gérer les plugins installés

Chaque carte montre l'état du plugin (Activé ou Désactivé) et propose :

Action	Effet
Activé / Désactivé	Démarre ou arrête le processus du plugin. Un plugin désactivé garde ses fichiers et sa configuration.
Config	Les réglages que le plugin déclare (une clé d'API, une ville, une unité...). Les champs secrets sont affichés masqués et ne sont jamais renvoyés au navigateur.
Logs	Les dernières lignes que le plugin a écrites par l'intermédiaire de l'hôte.
Désinstaller	Supprime le processus, les fichiers et les données stockées par le plugin.

Limites de ressources, en haut de la page, plafonne chaque processus de plugin. Les valeurs du panneau sont les défauts ; la variable d'environnement les fixe tant que le panneau n'a jamais été enregistré.

Champ	Défaut	Variable d'environnement
Mémoire max (Mio)	256	EVEY_PLUGINS_MEMORY_MB
Processus max	64	EVEY_PLUGINS_PIDS_MAX
Disque max (Mio)	100	EVEY_PLUGINS_DISK_MAX_MB
Nice CPU (0-19)	10	EVEY_PLUGINS_CPU_NICE
Mode sandbox	auto	EVEY_PLUGINS_SANDBOX_MODE

La mémoire, les processus et le disque s'appliquent au prochain balayage du moniteur, qui arrête un plugin qui les dépasse ; la priorité processeur et le mode sandbox s'appliquent aux plugins démarrés ensuite. 0 rétablit la valeur par défaut pour la mémoire et les processus ; seule la limite de disque traite 0 comme « désactivée ».

Le Tableau de bord sécurité conserve, par plugin, les constats de l'analyse, le résultat de la signature et la dernière erreur. Sa ligne Sandbox de l'hôte indique le mode de sandbox réellement appliqué sur cette machine : s'il affiche basic, l'hôte n'offre aucune isolation du système de fichiers par chemin, et Mise en place de la sandbox des plugins explique quoi changer.

Les plugins sont activés par défaut. EVEY_PLUGINS_ENABLED=false désactive tout le sous-système.

Ce qu'un plugin peut faire sur votre machine

Quoi que déclare son manifeste, un plugin :

• voit son propre dossier, pas les données du serveur ni les fichiers média ;
• n'a aucun accès direct au réseau : un plugin qui a la permission network n'atteint que les hôtes qu'il a déclarés, par l'intermédiaire du serveur, en GET et HEAD ;
• ne peut pas lancer de processus enfants sans déclarer subprocess ;
• tourne sous les limites de ressources ci-dessus et, quand l'hôte le permet, sous un utilisateur distinct.

Son interface est confinée aux emplacements que déclare le manifeste : une section ou la zone de bannière de l'accueil, un panneau latéral dans une bibliothèque ou sur une fiche, une surcouche du lecteur, les réglages d'apparence, le bas de la barre de navigation, ou une entrée du menu d'administration qui ouvre la page du plugin lui-même. Un plugin ne peut jamais rien afficher dans les écrans de connexion, d'installation, de sécurité ni dans les écrans d'administration existants. Dans son cadre, il n'a accès ni à la page, ni à vos cookies, ni à votre session : ce qu'il lit sur le serveur passe par un jeton de courte durée limité aux deux permissions qu'il peut demander (public pour une projection sûre des titres et affiches, prefs pour les préférences de l'utilisateur courant dans son propre espace).

Les permissions qu'un plugin peut demander sont listées dans Permissions et emplacements. Le fonctionnement de la sandbox, et ce qu'elle ne peut toujours pas empêcher, sont décrits dans Sandbox des plugins et modèle de menace.

Le serveur contrôle les hôtes que contacte un plugin, pas ce qu'il leur envoie

Une fois qu'un hôte figure dans la liste d'un plugin, le serveur ne peut pas inspecter ce que le plugin lui envoie. Examinez un plugin tiers avant de l'installer, comme n'importe quel logiciel, et considérez sa liste d'hôtes comme la liste des tiers qui peuvent recevoir les titres de votre bibliothèque.

Thèmes

Un thème est un paquet de kind: theme sans processus : une feuille de style et, en option, un script confiné dans un cadre caché. Il s'installe depuis la même fenêtre Installer un plugin ; la feuille de style est assainie à l'installation. Chaque utilisateur le choisit ensuite dans Paramètres → Apparence → Thème. Ce qu'un thème peut contenir est décrit dans Thèmes.

Écrire un plugin

Page	Contenu
Écrire un plugin	Un premier plugin pas à pas, la boucle d'installation, la signature, la distribution. À lire en premier.
Référence de l'API des plugins	Le manifeste, les appels backend et le stockage de données, le pont evey.* de l'interface.
Permissions et emplacements	Ce qu'un manifeste peut déclarer, ce qui est vérifié à l'installation, les règles d'accès externe, les emplacements.
Thèmes	Modifier l'apparence de l'interface avec du CSS et un script isolé.
Webhooks et clés d'API	Relier Evey à d'autres outils sans écrire de plugin.