Introduction aux WebExtensions

L’auteur rejette par avance tous les problèmes de sécurité ou de stabilité, ou de contournement des CGU, occasionnés par l’utilisation des exemples fournis dans le présent article, qui se veut strictement de sensibilisation et d’apprentissage.

Depuis longtemps le HTML n’est plus dérivé du XML, même s’il en garde une ergonomie générale : les balises meta par exemple, dans le head, ne sont pas fermées ; c’est pour cela que l’on parle souvent de soupe en évoquant le code (la « source ») HTML. Parser (ou traduire en bon français) du HTML avec un outil conçu pour le XML échouera. Cela ne veut pas dire que le HTML ne peut pas passer à du XML ou l’inverse – mais ce n’est pas forcément sans conséquences. Il existe par ailleurs « d’anciennes » variantes comme le XHTML, qui elles reprennent les canons du XML.

Nous ne verrons pas ici ces « bizarreries » de HTML vis-à-vis du XML : contentons-nous de savoir qu’un lien entre les deux existent et que le passage de l’un à l’autre peut être aussi possible, notamment en JavaScript.

XSL – eXtensible Stylesheet Language – est aussi vieux que le XML. Il est une feuille de route, une notice de changements à opérer du XML en entrée, vers tout autre langage « compatible » avec le XML (ou qui en est dérivé : PDF, HTML, etc) ou du XML pur. Ces changements sont des transformations, définies par plusieurs normes. XSL s’appuie sur XPath, en quelque sorte la grammaire d’une écriture des liens et des parentés entre les éléments XML.

JavaScript, lorsque vous utilisez un document « DOM » (compatible avec…), s’appuie en grande partie sur des réalisations, sur un « esprit » XML pour gérer l’arborescence de HTML. Celle-ci est simplement moins stricte, car l’héritage de HTML a été imprégné – c’est là une opinion toute personnelle – d’années de dérives d’IE (Microsoft) et de raccourcis pour de mauvaises raisons des développeurs du Web par la suite.

Il n’y a pas d’incompatibilité à utiliser XML en entrée pour produire du HTML, y compris la 5e version du nom. Avec un peu de verve, une de mes actualités évoquait ces liens et l’utilisation des transformations pour générer des pages côté client. Nous utiliserons un principe similaire ici, en partie à cause d’un cadre avec des différences de contraintes vis-à-vis de ce qu’est le Web classique, celui côté client « page ».

En résumé :

• XML est un format de données statiques, tout comme HTML, qui hérite de certaines propriétés de XML ;
• XSL est un format de données des transformations à faire sur XML ;
• XPath permet des opérations de parcours complexe d’une arborescence XML. On parle également de « localisation » dans un arbre pouvant être représenté comme des ensembles d’éléments imbriqués ;
• L’ensemble est mixé par un moteur dédié (il en existe plusieurs), à partir d’une même norme, qui définit en outre des fonctions appelables au sein de XSL.

Nous verrons plus loin dans cet article des limitations fortes dans le cadre des WebExt, notamment du côté de l’évaluation d’expressions ; je n’entre pas ici dans le détail. Gardons pour principe qu’en dehors de l’utilisation d’un pseudo-langage – avec le temps de développement / test, la complexité vis-à-vis de la finalité et la courbe d’apprentissage côté utilisateur ; bref caduque dans notre cas –, peu de solutions existent.

Or un code source HTML reçu d’un serveur, même avec un pattern matching des URL, reste très variable en fonction de chaque site et en fonction de chaque page sur un site. Il y a toujours la possibilité de faire un seul et même « moteur » pour récupérer l’information intéressante (et c’est par exemple offert avec certains navigateurs par le biais du mode « lecture »), mais cela reste de l’arbitraire du développeur : peut-être que l’utilisateur a d’autres souhaits, d’autres besoins.

Pour donner un peu de souplesse dans un tel cas, le XSL est le meilleur. Pas le plus simple, pas le plus facile, pas le moins fastidieux, mais probablement le plus efficace. Si seule la première version de la norme est implémentée largement dans les navigateurs (tous pour ceux qui supportent les WebExt), la seconde version, bien plus pointue et astucieuse, n’est pour ainsi dire pas disponible sauf à passer par des tiers.

De plus le XSL n’est jamais qu’une chaîne de caractères qui se stocke donc très bien (soit par stockage.local soit par IndexedDB), se parse en Javascript sans difficulté et s’applique à un objet Document (DOM).

Alors comment faire ?

Simplement : s’il supporte les WebExtension, notamment à partir de la version 57 de Firefox (en réalité antérieurement, mais l’API est réduite car le multiprocessus n’y est pas encore la norme) et la version 25 de Chrome (même les WebExtensions n’étaient pas alors dans une version normée définitive), alors il est très probable que votre navigateur supporte la plupart de ce que je décris dans cet article.

Les WebExtensions sont une bonne introduction à la richesse – et son pendant, un relatif bazar – qu’entoure désormais le langage « du Web, pour le Web » à tous les niveaux. La banche de JS à la sauce NodeJS, et son célèbre moteur V8, est probablement l’un des aspects les plus connus. Pourtant l’évolution touche également les clients.

J’ai regroupé ici les principales familles de ce côté « client » et qui nous intéressent dans le cadre d’une utilisation sur le navigateur. À chaque fois c’est bien le même langage (une même version), le même environnement (le navigateur) mais pas le même contexte (et donc pas la même disponibilité d’API), portant aussi sur la portée de certaines variables (en écriture et en lecture).

Ce tableau qui tente une synthèse probablement très critiquable et partielle, s’appuie sur la documentation du MDN et est une construction personnelle. En jaune, vous trouverez les scripts « habituels », insérés dans une page et que nous avons l’habitude de voir dans les tutoriels et autres exemples. En gris, ceux sur lesquels s’arrêtera principalement cet article.

Ainsi nous pouvons tirer de ce tableau et de la documentation, quelques points-clé pour bien comprendre quoi utiliser et quand en trois grands points (donc résumé arbitraire) :

• la portée du script, c’est-à-dire sur quel aspect d’une ressource (page, DOM, bases de données, etc) ou d’une interface (Workers, etc) il agira. Par exemple pour un script de contenu :

  • a-t-il un accès direct ou indirect à une ressource → accès direct à l’espace de stockage de la WebExtension et du DOM de la page où il s’exécute ;
  • partage-t-il la possibilité directe d’une lecture et/ou écriture de variable → si un script de contenu a accès au DOM, il ne verra pas et ne peut modifier les variables associées à l’objet Document ou Window des scripts de page ;

• sa nature, c’est-à-dire s’il est à vocation strictement synchrone, mixte ou strictement asynchrone :

  • un code bloquant dans une vocation strictement synchrone bloquera tout le script → ex. le fonctionnement originel de JS sur les navigateurs,
  • un code bloquant dans une vocation mixte, peut bloquer tout ou partie d’un script ou l’utilisation d’une ressource → ex. actuellement sur un script de page qui utilise à la fois du code synchrone et de la gestion d’événements, ainsi que des appels à des Workers,
  • un code bloquant dans une vocation strictement asynchrone pourra retourner une erreur et celle-ci peut-être silencieuse → ex. script d’arrière-plan d’une WebExtension (l’erreur apparaît dans les logs seulement du navigateur) ou script de ServiceWorker gérant un cache (l’erreur apparaît dans les log de la page où il est lancé) ;
• son intérêt ; c’est-à-dire à quoi il est traditionnellement assigné, comme je l’indique plus haut. Son intérêt est souvent lié au moment du déclenchement dans l’ensemble des événements possibles sur un navigateur (qui ne se limite pas, encore une fois, à quelques pages… !).

Le choix d’un site pour cette première partie, n’a pas été anodin. Il s’agit d’un site commercial, avec énormément de scripts de pages internes et externes, notamment publicitaires, de nombreuses ressources mais un code qui reste relativement clair et un contenu structuré (pouvant être tabularisé pour l’exercice). Surtout, la mise à jour intervient à un rythme régulier (une fois par jour), qui nous permet de faire des tests sur un temps long et pouvant facilement être appréhendé. Enfin,un point & non des moindres : vous pouvez tester indifféremment par HTTP et HTTPS sur cette page, qui retourne la même chose (et ainsi constater qu’effectivement, vous n’agissez pas ici sur la connexion mais bien sur la requête qui transite sur la connexion).

Voici l’URL sur laquelle travailler (les autres pages ne nous intéresseront pas ici) : http://www.programme-tv.net/programme/programme-tnt.html

Voici que vous pourriez voir sans transformation de la page :

Voici ce que vous devriez voir après transformation :

Notez qu’aucun script de la page initiale (celle renvoyée par le serveur, avec les scripts publicitaires) n’aura été finalement chargé après la transformation. Pour arriver à ce résultat, nous aurons les étapes suivantes :

1. avant la requête…

   1. ajouter une fonction aux écouteurs d’événement,
   2. procéder à un filtrage par motif (pattern matching) ainsi que par type (ici les codes sources des pages dites main_frame, jamais des frames incluses dans une page) ;

2. au niveau de la requête en elle-même…

   1. récupérer le corps de la réponse, pour en produire du « texte », qui sera échappé et introduit dans une page HTML type ;
   2. renvoyer cette page type comme réponse à interpréter dans le bon format ;

3. au niveau de la page (du code source) renvoyée…

   1. une fois cette page type avec le contenu original de la requête chargée dans l’onglet, procéder à l’analyse (DOMParse) et aux transformations XSL,
   2. réinjecter dans la source HTML transformé, son objet DOM, dans la page qui a servi de support.

Pourquoi traiter les transformations XSL au sein d’un onglet et non directement lors de la réception du contenu original ? Plusieurs raisons m’ont poussé à ce choix :

• ne pas perdre du temps : lorsque l’utilisateur demande une page, lorsqu’il demande une URL ou parce qu’elle est chargée à l’ouverture d’un onglet, il souhaite connaître l’état d’avancement. Renvoyer une page type, qui indique tout de suite l’interception, l’état actuel de chargement, la possibilité d’annuler la transformation et l’avancement de la transformation, puis se chargera d’être le « support », permet à la fois une information complète et une meilleure maîtrise ;
• circonscrire les erreurs : si votre script rencontre une erreur sur la transformation d’une page, mieux vaut qu’un plantage ou un ralentissement soit au niveau de l’onglet qu’au niveau de la WebExt ;
• fractionner le développement : la récupération est un processus différent de la transformation, géré par un autre script. Une évolution de l’un ne touche pas l’autre et pour la relecture par un tiers, en plus des commentaires, les scripts ainsi « découpés » sont moins indigestes.

Pour les transformations, nous utiliserons les seules fonctions natives JS du navigateur, en passant d’un code source HTML à un objet Document puis la transformation de ce dernier avec un contenu XSL parsé.

Dans notre phase précédente, nous avons installé une WebExt vide, sans aucune permission, ainsi qu’un fichier de script d’arrière-plan. Pour détecter des requêtes intéressantes, il ne s’agit pas juste de « lire » l’URL et de la comparer à un motif : encore faut-il, une fois détectée, pouvoir extraire de la ressource qui y sera associée (ici du contenu HTML), ce qui nous intéresse. Et mieux : modifier cette ressource.

Il nous faudra aussi stocker notre transformation XSL, qui sera appliquée… Ici nous n’en stockerons qu’une, pour l’exemple, qui sera éditable dans la seconde partie. Pour une seule transformation, ouvrir un espace de stockage, au détriment d’une simple variable, n’est pas utile. C’est pourquoi dans la seconde partie, nous pourrons « rentabiliser » cet espace ouvert en pouvant créer de nouvelles transformations. J’ai également utilisé l’espace de stockage pour une page type, j’en détaillerai plus loin la raison.

Mettons donc tout d’abord les permissions nécessaires à notre script. N’oubliez pas qu’à chaque étape, si vous n’utilisez pas l’outil web-ext mentionné plus haut, vous devrez recharger manuellement votre WebExt afin que les modifications soient prises en compte.

La partie permissions du fichier manifest.json, doit désormais ressembler à cela :

{
   "permissions": [
      "unlimitedStorage",
      "storage",
      "webRequest",
      "webRequestBlocking",
      "<all_urls>"
   ]
}

Les deux premiers items vous permettent d’accéder à une ressource de stockage pour la WebExt – c’est-à-dire indépendamment des autres espaces de stockage notamment ceux liés aux domaines visités. En réalité, Firefox considère l’ID de l’extension comme un domaine à part entière, et repose donc sa stratégie de stockage pour la WebExt comme il le ferait pour n’importe quel site Internet. L’item unlimitedStorage n’a pas d’utilité dans notre exemple ; je le donne à titre d’information. Il ne s’applique pas d’ailleurs au stockage sync mais seulement aux stockages locaux – c sync étant celui qui est synchronisé entre les différentes instances connectées à un même compte (ex. Firefox Sync ou votre compte Google pour Google Chrome) et dont les règles de quota sont gérés par ces mêmes services.

→ Bon à savoir : Firefox, comme d’autres navigateurs, ne garantit pas la préservation « impérative » des données – c-à-d que vous pourriez avoir des données effacées sans que la navigateur ne le demande à la WebExtension voire ni même ne l’alerte. Un critère temporel (l‘accès le plus vieux à une base) est utilisé, puis un effacement dans la base la plus ancienne sans critère précis indiqué (aléatoire?).
Si pour un poste fixe récent, la quantité de mémoire « en dur » est bien plus que suffisante en dehors de certains usages (jeux, calculs scientifiques, etc) ; ce qui n’est pas le cas pour les périphériques mobiles. Un paragraphe sera dédié au cas des WebExtensions sur périphérique mobile dans la conclusion de l’article.
Attention donc, à ne pas considérer cette base comme une base de données « définitive » comme peut l’être par exemple MySQL, qui arrêtera simplement l’enregistrement de nouvelles données. Vous devez toujours considérer qu’il s’agit ici d’un SGBD à vocation « temporaire » ou au moins d’un système « incertain », quand bien même le cas n’aurait pas de raison de présenter, par le simple fait qu’il est possible.

Les autres items sont eux plus intéressants et permettent le suivi de toutes les requêtes (quel que soit le format de celles-ci, j’y reviendrai), ainsi que leur manipulation comme peut être traduit webRequestBlocking. L’item <all_urls> est en quelque sorte « un opérateur », que l’on peut retrouver dans d’autres parties des API WebExtension et dont l’usage implique une absence de restriction sur les URL pouvant être ainsi « gérées », quel que soit le protocole (HTTP ou HTTPS). Attention, le domaine du magasin d’applications pour Firefox ou pour Chrome, est naturellement inviolable par les WebExtension, afin d’éviter toute manipulation, ainsi que certains protocoles liés au fonctionnement du navigateur (une WebExt ne peut pas, par exemple, agir sur ses propres requêtes – ou globalement lorsqu’il s’agit du protocole moz-extension://).

Au sein du fichier background.js, des ajouts sont à prévoir. Je vais tenter de résumer schématiquement comme l’utiliser pour le mieux :

• en qualité de script d’arrière-plan lorsque le navigateur démarre avec une WebExt déjà installée, il est déclenché au moment du lancement du navigateur. En réalité ce dernier est déjà lancé et votre script intervient entre la fin du chargement des principaux organes du navigateur, et le démarrage du lancement du ou des premiers onglets affichés à l’utilisateur (le navigateur étant ici un « client » des données). C’est important de se rappeler cela : vous ne pourrez jamais être avant ce moment du chargement, par ce qui est offert dans un script d’arrière-plan. Dans certains cas, notamment lorsque des WebExt agissent sur une même fonction, vous ne pouvez donc pas être certains que ce qui arrive à votre WebExt n’a pas déjà été modifié ou stoppé par une autre(1) ;
• contrairement à d’autres scripts qui doivent être « véritablement » asynchrones (notamment les scripts de ServiceWorker à vocation de gestion d’un cache local), les scripts d’arrière-plan sont tout à fait synchrones (donc pouvant être bloqués par une opération) et sont surtout utiles pour formaliser (au sens d’une déclaration de fonction) et enregistrer les interceptions d’événements.

Nous allons d’abord déclarer une fonction – listener – qui servira à traiter les requêtes intéressantes. Non pas à les filtrer, car cela n’est rendu possible que par l’enregistrement d’une écoute d’événement qui réagit aux requêtes correspondant à un motif (pattern matching) que nous verrons plus loin :

browser.SurveilleURLs = [ 
  "*://www.programme-tv.net/programme/programme-tnt.html" 
];  // → l'objet 'browser' est l’équivalent de 'window' pour un script de page, et tous les appels de toutes les API des WebExt passent par cet objet  

function listener(details) {
  let filter = browser.webRequest.filterResponseData( 
    details.requestId 
  ); 
  let tabBuffer = [];  // → on reçoit du binaire ! Pas du texte 
  filter.ondata = event => { 
    tabBuffer.push(event.data); // → à chaque réception d’une portion de la réponse, on ajoute cette portion de code binaire à notre tableau qui sert de 'buffer' 
  } 
  filter.onstop = event => { // → fin de la réception des portions 
    var source = new Blob(tabBuffer, {type : 'text/html'}); 
    console.log(source); 
    filter.write(source); // → on renvoie directement la source sans modification pour la poursuite 
    filter.disconnect();  // → on arrête l’écoute   
  } 
}

Dans la console du navigateur et pas la console d’une page ouverte (« Débogger des modules » dans le menu général des WebExt), vous verrez le contenu de la source ainsi interceptée.

Cela devrait ressembler à cette ligne :

Blob { size: 276530, type: "text/html" }

Nous positionnons auparavant cette fonction dans un écouteur d’événement, grâce à l’API offerte par webRequestBlocking :

browser.webRequest.onBeforeRequest.addListener( 
    listener,
    {    
        urls: browser.SurveilleURLs, // → mettre '<all_urls>' pour intercepter toutes les pages sources disponibles 
        types: [ 
            "main_frame" // → seulement les pages « sources » (pas les iframes, les images, scripts, CSS, etc). De toute façon leur chargement intervient sur instruction de la source : si celle-ci est modifié, leur chargement n’existera pas 
        ] 
    }, 
    [ 
        "blocking" 
    ] 
);

J’ai choisi d’indiquer une interception avant la requête elle-même – onBeforeRequest –, afin de nous assurer que cette requête, si elle aboutit (même en cas de retour 404 ou 500), soit correctement « écoutée » et modifiée dans notre cas.

→ Bon à savoir : il est souvent noté qu’un écouteur d’événement est une fonctionnalité du DOM pour les pages. C’est incomplet : le Document Object Model regroupe l’ensemble des événements qui sont liés aux contenus et à leurs traitements au sein d’un logiciel (ici le navigateur). C’est en quelque sorte la même « recette » qui est appliquée pour chacun des « événements » qui sont suivis (c-à-d schématiquement un changement d’état d’une fonction ou d’une variable), permettant d’unifier les écouteurs et les interceptions.
Ainsi un DOM pour HTML est voisin d’un DOM pour des événement HTTP ou lié au fonctionnement du navigateur (ouverture d’un onglet, d’un menu, etc).

Si votre WebExt est rechargée et que vous chargez la page surveillée, vous verrez désormais… une magnifique page vierge (et une page normale partout ailleurs, sauf dans le cas <all_urls> évidemment). Incompréhensible : n’a-t-on pas fourni le contenu avant de désactiver notre interception ?

Le problème c’est que ce que vous renvoyez ne correspond pas à ce que Firefox attend en terme de format (pas d’encodage, je parle bien de format). Il ne peut pas du binaire avec un flag (un drapeau) text/HTML, mais l’équivalent d’une chaîne de caractère dans le langage JS.

function listener(details) {
  let filter = browser.webRequest.filterResponseData( 
    details.requestId 
  ); 
  let tabBuffer = [];  // → on reçoit du binaire ! Pas du texte au sens JS  
  let encoder = new TextEncoder(); // → on va vraiment "comprendre" le binaire comme du texte 
  filter.ondata = event => { 
    tabBuffer.push(event.data); 
  } 
  filter.onstop = event => {
    var source = new Blob(tabBuffer, {type : 'text/html'}); 
    var reader = new FileReader(); 
    reader.addEventListener("loadend", function(resultat) { 
      console.log(resultat.target.result); // ici le résultat comme du texte "source" HTML classique 
      filter.write(encoder.encode(resultat.target.result)); 
      filter.disconnect();

    }); 
    reader.readAsText(source); 
  } 
}

Nous avons cette fois-ci la page qui est affiché à l’utilisateur et dans la console du navigateur, le texte « source » HTML.

Je vais également ajouter les lignes de code pour définir les objets dans l’espace de stockage Storage, que nous utiliserons après.

II-B-4-a. Code source actuel du fichier background.js▲

self.transformationDefaut = `<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="html" doctype-system="about:legacy-compat" encoding="UTF-8" omit-xml-declaration="yes" indent="yes" />
  <xsl:template name="colonne_NomChaine"> 
    <td> 
      <xsl:value-of select=".//a[contains(@class, 'channel_label')]/@title" /> 
    </td> 
    </xsl:template> 
  <xsl:template name="colonne_NomProgramme"> 
    <td> 
      <xsl:value-of select=".//a[contains(@class, 'prog_name')]/@title" /><br /> 
      <xsl:value-of select=".//span[contains(@class, 'prog_type')]/text()" /> 
    </td>   
    </xsl:template> 
  <xsl:template name="ligne_Chaine"> 
    <tr> 
      <xsl:call-template name="colonne_NomChaine"></xsl:call-template> 
      <xsl:for-each select=".//div[contains(@class, 'programme')]"> 
        <xsl:call-template name="colonne_NomProgramme"></xsl:call-template> 
      </xsl:for-each> 
    </tr> 
    </xsl:template> 
  <xsl:template match="/">
    <html>
      <head>
        <title>
          <xsl:value-of select="/html/head/title"/>
        </title> 
      </head>
      <body> 
        <table> 
          <thead> 
            <tr> 
              <td colspan="3">Chaînes</td> 
            </tr> 
          </thead> 
          <tbody> 
            <xsl:for-each select="//div[contains(@class, 'p-v-md')]"> 
              <xsl:call-template name="ligne_Chaine"></xsl:call-template> 
            </xsl:for-each>
          </tbody> 
        </table> 
      </body> 
    </html> 
  </xsl:template>
</xsl:stylesheet>`; 

browser.storage.local.set( 
  { 
    "transformation:defaut": self.transformationDefaut  
  }
); 

self.pageDefaut = `<!DOCTYPE html>
<html lang="fr">
<head>
<meta charset="utf-8">
<title>ControlePage</title> 
</head>
<body> 
  <code id="ControlePage"></code> 
  <header> 
    <h1>WebExtension 'ControlePage'</h1> 
    <p class="info"> 
      Cette page a été interceptée 
      car elle répond à un schéma défini 
      dans le base de données de la WebExtension. 
    </p> 
  </header> 
  %page% 
  <footer> 
    <p> 
      Etat de la page : 
        <span id="etat"> 
          en attente d'être traitée... 
        </span> 
    </p> 
  </footer> 
</body>
</html>`; 

browser.storage.local.set( 
  { 
    "page:defaut": self.pageDefaut 
  }
); 

/*---*/ 

browser.SurveilleURLs = [ 
  "*://www.programme-tv.net/programme/programme-tnt.html", 
]; 

browser.TransformationsURLs = [ 
  { 
    "url": "http(s)?://www.programme-tv.net/programme/programme-tnt.html", 
    "transformationId" : "defaut" 
  } 
]; 

browser.storage.local.set( 
  { 
    "transformations:urls": browser.TransformationsURLs 
  }
); 

/*---*/ 

function listener(details) {
  let filter = browser.webRequest.filterResponseData( 
    details.requestId 
  );
  let encoder = new TextEncoder(); 
  let tabBuffer = []; 
  filter.ondata = event => { 
    tabBuffer.push(event.data); 
  } 
  filter.onstop = event => { 
    var source = new Blob(tabBuffer, {type : 'text/html'}); 
    var reader = new FileReader(); 
    reader.addEventListener("loadend", function(resultat) { 
      browser.storage.local.get("page:defaut").then( 
        (objRStockage) => { 
          if (Object.keys(arg1).length<1) { 
            var page = self.pageDefaut; 
            var texte = "<div id=\"erreur\"><p>Oups, la web extension est en panne !</p></div>"; 
          } else { 
            var page = objRStockage["page:defaut"];
            var texte = "<div id=\"chargement\"></div><template id=\"pageSource\">"+encodeURIComponent( 
              resultat.target.result 
            )+"</template>" 
          } 
          texte = page.replace( 
            "%page%", 
            texte 
          ); 
          filter.write(encoder.encode(texte)); 
          filter.disconnect(); 
        } 
      ); 
    }); 
    reader.readAsText(source);
  } 
} 

browser.webRequest.onBeforeRequest.addListener( 
    listener,
    {    
        urls: browser.SurveilleURLs, 
        types: [ 
            "main_frame" 
        ] 
    }, 
    [ 
        "blocking" 
    ] 
);

En ouvrant la console de la page, notez que j’ai utilisé la balise template, dont j’évoquerai les qualités et usages plus loin dans l’article, à dessein. Elle contient la source HTML originale de la requête, celle reçue du serveur, en version textuelle échappée. Cette source originale est donc inerte et n’est pas traitée par le navigateur : l’onglet Réseau de la console, vous indique ainsi qu’aucun autre chargement de ressource ne se produit, ce qui est logique.

Ce qui est moins logique par contre, c’est lorsque vous regardez dans ce même onglet Réseau, la réponse de la requête… Vous trouvez la source originale et non notre page type ! Idem si vous ajouter view-source : à votre URL, indiquant que vous souhaitez voir seulement le contenu HTML. Seul l’Inspecteur, onglet qui permet de parcourir le document HTML en temps réel, vous donne la page type. Pourquoi un tel comportement ? D’abord une raison pratique : comme je vous l’indiquais, votre WebExt ne dispose que d’une ressource qui lui est attribué par le navigateur, à un moment donné. Le navigateur, lui, peut disposer de toutes les versions et donner à chaque composant une version ou une autre. Vous ne disposez pas « totalement » de la capacité à modifier un contenu « original », seulement dans un contexte un contenu « dupliqué »…

C’est ensuite une raison de sécurité : l’utilisateur a un outil fiable, la console de la page, disponible pour chaque onglet, qui lui permet de voir si le traitement d’une page, sa source, est celle reçue du réseau ou a été modifiée. Évidemment sur le cas d’un site complexe comme le webmail de Google ou globalement des interfaces utilisant React ou équivalent, une telle vérification n’a pas grand sens vu (1) la complexité du code, (2) une génération de chaque composant en temps réel.

Bien : votre page type s’affiche mais toujours pas la transformation du contenu désiré. Nous allons devoir « injecter » du code Javascript quelque part. Et tant qu’à faire, « proprement », sans utiliser le code source. Avec une WebExt, c’est possible et c’est facile, toujours grâce aux motifs et aux écouteurs d’événements.

Voici un exemple de ce qui se passera : le navigateur ira chercher la page d’un célèbre site d’annonces en ligne (nous voyons dans la console de l’onglet que c’est bien le cas), et notre WebExtension ne lui retournera que ce qu’il lui chante :

Allons-y ! Dans notre fichier background.js, insérez le code suivant :

browser.contentScripts.register({
  "js": [{file: "/surveille.js"}], 
  "css": [{file: "/commun.css"}], 
  "matches": ["<all_urls>"], // ou browser.SurveilleURLs pour faire du pattern matching 
  "runAt": "document_idle"
});

Vous avez déjà deviné l’intérêt : créer le fichier à la racine de la WebExt, le fichier surveille.js et commun.css.

Dans ce dernier, modifiez le contenu avec le CSS suivant :

body { 
    background: rgba(0,0,255,0.15); 
} 

table * { 
    text-align: center; 
}

Dans le premier, ajouter le code JS suivant :

console.log("ControlePage :: nouvelle page suivant le résultat du 'pattern matching'");

… puis regarder ce qui se passe pour chaque page, notamment sur Google où le fond de la page n’est plus blanc ! Avec le message dans la console de l’onglet.

Nous avons bien une insertion après le chargement du DOM et de l’ensemble des ressources, de nos deux fichiers de WebExt. Logique ! l’attribut runAt dans l’objet passé en argument de l’écouteur, définit le moment du chargement des ressources. « Notre » CSS prend donc le pas sur le reste car c’est le dernier a être chargé (écrasement des attributs). Nous verrons dans la seconde partie de cet article, les pièges qui existent avec cette méthode et dans quel cas ne pas l’utiliser.

Vous pouvez repasser ["<all_urls>"] à la la variable browser.SurveilleURLs, ce qui restreindra cette injection à nos URL définies. Modifiez le script surveille.js avec le contenu suivant :

console.log("ControlePage :: nouvelle page suivant le résultat du 'pattern matching'"); 

function Transformer(SourceTexteXSLT, SourceTexteHTML) { 
    var parseurXSLT = new DOMParser();
    var docXSLT = parseurXSLT.parseFromString( 
        SourceTexteXSLT, 
        "text/xml" 
    ); 
    var parseurHTML = new DOMParser(); 
    var docHTML = parseurHTML.parseFromString( 
        SourceTexteHTML, 
        "text/html" 
    ); 
    var processeurXSLT = new XSLTProcessor(); 
    processeurXSLT.importStylesheet( 
        docXSLT 
    ); 
    return processeurXSLT.transformToFragment( 
        docHTML, 
        document 
    ); 
} 

browser.storage.local.get( 
    "transformations:urls" 
).then( 
    (objResultTous) => { 
        var regExt =  new RegExp(""); 
        var docURL = ""+window.location.href; 
        try {
            objResultTous["transformations:urls"].forEach( 
                (objResultUn) => { 
                    regExt.compile( 
                        objResultUn["url"] 
                    ); 
                    if (regExt.test(docURL)) { 
                        browser.storage.local.get( 
                            "transformation:"+objResultUn["transformationId"] 
                        ).then( 
                            (retour) => { 
                                var sourceTexteBrut = document.querySelector("template#pageSource").innerHTML; 
                                var sourceTexte = decodeURIComponent( 
                                    sourceTexteBrut 
                                ); 
                                var docXHTML = Transformer(  
                                    retour["transformation:defaut"], 
                                    sourceTexte   
                                ); 
                                [ 
                                    "head", 
                                    "body" 
                                ].forEach(
                                    (element) => {
                                        var elNouveau = docXHTML.querySelector( 
                                            element 
                                        ); 
                                        var elOrigine = document.querySelector( 
                                            element 
                                        ); 
                                        elOrigine.parentElement.replaceChild( 
                                            elNouveau, 
                                            elOrigine 
                                        ); 
                                    }
                                ); 
                                var elTemplate = document.createElement("template"); 
                                elTemplate.textContent = sourceTexteBrut; 
                                elTemplate.setAttribute("id", "pageSource"); 
                                document.querySelector("body").appendChild( 
                                    elTemplate 
                                ); 
                                console.log("ControlePage :: fin de la génération de la page suivant la transformation donnée"); 
                            } 
                        ); 
                        throw BreakException;
                    } 
                }
            ); 
        } catch (erreur) {
          if (erreur !== BreakException) 
              throw erreur; 
        }
    }
);

Ça y est : votre page apparaît, belle et bien transformée par XSL. En modifiant la source de la transformation, vous agirez sur la présentation. Avec CSS et Javascript, une fois injectés et par la suite avec des appels supplémentaires, vous pouvez également maîtriser plus en profondeur ces transformations. Vous pouvez également récupérer des ressources initialement demandées par la page d’origine : tout est possible.

Avec, pourquoi pas, la possibilité de vous faire un moteur des informations collectées, une sorte de moteur de recherche avancée, dans le contenu d’un historique qui ne se limite pas à la paire URL / titre de la page !

II-B-5-a. Et sans XSL malgré tout ?▲

C’est toujours possible mais, comme nous le verrons dans cet article, l’évaluation d’expression n’est pas possible au sein d’une WebExtension ce qui en limite considérablement l’usage (et même si c’est – presque – possible par le biais d’un hack sur la page, c’est de toute façon totalement décommandé).

Il faudra alors avoir recours à du JS codé « en dur » dans le script qui, s’il n’est pas compliqué, n’offre que peu le loisir d’être modifié par l’utilisateur :

 

Cacher/Afficher le codeSélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
95.
96.
97.
98.
99.
100.
101.
102.
103.
104.
105.
106.
107.
108.
109.
110.
111.
112.
113.

var sourceTexte = decodeURIComponent( 
    document.querySelector("template#pageSource").innerHTML 
); 

var parser = new DOMParser(); 
var doc = parser.parseFromString( 
    sourceTexte, 
    "text/html" 
); 

var blocChaines = ".p-v-md"; 
var blocProgrammes = ".programme"; 

var chainesListe = doc.querySelectorAll( 
    blocChaines 
); 
var chaines = []; 
chainesListe.forEach( 
    (blocChaine, i, tab) => { 
        var chaine = blocChaine.querySelector( 
            "a.channel_label" 
        ).getAttribute( 
            "title" 
        ).replace( 
            "Programme de ", 
            "" 
        ); 
        var programmes = []; 
        var blocImages = blocChaine.querySelectorAll( 
            ".programme" 
        ).forEach( 
            (blockProgramme) => { 
                var nom = blockProgramme.querySelector( 
                    "a.prog_name" 
                ).getAttribute( 
                    "title" 
                ); 
                var type = blockProgramme.querySelector( 
                    ".prog_type" 
                ).textContent; 
                programmes.push( 
                    { 
                        "nom": nom, 
                        "type" : type  
                    } 
                ); 
            } 
        ); 
        chaines.push( 
            { 
                "nom": chaine, 
                "programmes": programmes
            } 
        ); 
    } 
); 

var tableau = document.createElement("table"); 
tableau.setAttribute( 
    "border", 
    1 
); 
var tableau_entete = document.createElement("thead"); 
var tableau_entete_ligne = document.createElement("tr"); 
var tableau_entete_colonne1 = document.createElement("td"); 
tableau_entete_colonne1.textContent = "Chaînes disponibles"; 
tableau_entete_colonne1.setAttribute( 
    "colspan", 
    3 
); 
tableau_entete_ligne.appendChild( 
    tableau_entete_colonne1 
); 
tableau_entete.appendChild( 
    tableau_entete_ligne 
); 
var tableau_corps = document.createElement("tbody"); 
chaines.forEach( 
    (chaine) => { 
        var tableau_corps_ligne = document.createElement("tr"); 
        var tableau_corps_colonne1 = document.createElement("td"); 
        tableau_corps_colonne1.textContent = chaine["nom"]; 
        tableau_corps_ligne.appendChild( 
            tableau_corps_colonne1 
        ); 
        chaine["programmes"].forEach(
            (programme) => { 
                var tableau_corps_colonne = document.createElement("td"); 
                var tableau_corps_nom = document.createElement("div"); 
                tableau_corps_nom.textContent = programme["nom"];
                tableau_corps_colonne.appendChild( 
                    tableau_corps_nom 
                ); 
                var tableau_corps_type = document.createElement("div"); 
                tableau_corps_type.textContent = programme["type"];
                tableau_corps_colonne.appendChild( 
                    tableau_corps_type 
                ); 
                tableau_corps_ligne.appendChild( 
                    tableau_corps_colonne 
                ); 
            } 
        ); 
        tableau_corps.appendChild( 
            tableau_corps_ligne 
        ); 
    } 
); 


tableau.appendChild(tableau_entete); 
tableau.appendChild(tableau_corps); 
document.body.appendChild(tableau); // → même résultat qu’avec XSL!

Le résultat sera conforme à ce que nous attendons. Notez qu’il y a une subtile nuance pour les noms de chaînes, qui sont le contenu exact des titres, avec le préalable systématique « Programme de… » :

Avant de rentrer dans notre sujet, comprenons notre contexte en détail. Dans un script de contenu ou d’arrière-plan (ou par la console du débug des WebExt, pas par la console d’une page!), testez le code suivant :

Function("console.log('ok');");

… la réaction ne se fait pas attendre et l’évaluation de texte composant le corps de la fonction n’est pas exécutée. Ainsi Function est un « équivalent » (à gros traits) de la fonction eval – à cette différence que la première est une fonction qui en retourne une « prête à l’emploi » et non une évaluation destinée à une exécution immédiate. Vous devriez avoir le message suivant dans une console liée à la WebExt :

>> Function("console.log('ok');");
Error: call to Function() blocked by CSP debugger eval code:1:1 
Content Security Policy: Les paramètres de la page ont empêché le chargement d’une ressource à self (« script-src »). Source: call to eval() or related function blocked by CSP. debugger eval code:1:1

Dans un contexte de script de page, ou de la console d’une page « classique », le résultat est bien une fonction anonyme :

>> Function("console.log('ok');");
anonymous()
arguments: null
caller: null
length: 0
name: "anonymous"
prototype: Object { … }
<prototype>: function ()

Vous pouvez donc « exécuter » cette fonction anonyme. Je vous invite à lire la documentation afférente (ainsi qu’un chapitre en sus ici) et à tester en dehors de ce tutoriel ces notions avant d’aller plus loin.

Ce que vous devez garder à l’esprit, c’est qu’une des limitations – sinon la limitation majeure –, des WebExt est l’évaluation d’expressions. Elle est strictement interdite en tout lieu(2). Ce comportement est une CSP – Content Security Policy (ici géré par le navigateur lui-même) – dont hérite par exemple le refus d’une requête cross-domain.

Pour faire simple : les règles entre page Web et WebExt sont des inverses sur ces sujets. Le cross-domain est permis (avec les droits associés obtenus), mais l’évaluation ne l’est pas. La raison est évidente : éviter qu’un assaillant puisse exécuter en contexte d’arrière-plan ou de script de contenu, du code arbitraire. Y compris si ce code est une chaîne « en dur » dans votre script initial.

Or certains outils de mise au gabarit, dont la qualité est inégale par ailleurs, souvent lourds pour peu d’opérations, peuvent être amenés à utiliser l’évaluation d’expressions de manière légitime. Aussi je vous déconseille fortement l’utilisation des bibliothèques « toutes prêtes » qui ne sont pas spécifiquement conçues pour les WebExt. D’abord leur récupération par le navigateur imposerait d’exposer la WebExt à du code extérieur (avec des complications pour que leur contenu soit exécuté si cela passe par une requête!), ce qui est déjà en soi un risque, mais de plus les bibliothèques peuvent provoquer des erreurs dues à la configuration particulière de leur environnement.

Le mieux si vous souhaitez en utiliser, est leur intégration dans le projet en tant que tel (donc « figer » la version utilisée) et en prenant un soin minutieux à connaître leur fonctionnement interne.

La solution la plus simple est de passer par ce qui est offert par le navigateur et l’évolution de HTML. La version 5 prévoit ainsi une balise template qui agit d’une manière similaire à ce que serait un DocumentFragment. La balise, qui est insérée dans dans le code source HTML, fait partie du DOM mais n’est pas prise en compte pour l’affichage par le navigateur : il n’y a donc aucun rendu (aucune règle CSS ne devant lui-être directement associée). Elle est appelable par les fonctions de sélection CSS cependant, ce qui lui permet d’être utilisé indépendamment par .getElementByTag(Class)Name ou par .querySelector.

Son appel par JS retourne une entité HTML un peu particulière (comme la balise form retourne par exemple une liste accessible d’entrées, pouvant se comporter comme un tableau). Ici le contenu du gabarit est accessible par l’attribut .content de l’objet template. Ce contenu peut être modifié et/ou cloné à volonté, par exemple pour reproduire un même formulaire, un tableau, etc – ou même un fil d’actualité.

L’usage, comme vous pourrez en avoir un aperçu dans la source que je donne pour l’éditeur, est très souple en plus de correspondre strictement aux spécifications du W3C.

Car, dernier point à garder à l’esprit, certaines pratiques – si elles sont toujours possibles – sont déconseillées pour les WebExt. Ainsi l’évaluation de HTML est possible quand l’évaluation JS ne l’est pas, mais la validation et la publication sur une plateforme – notamment celle de Mozilla – provoquera une alerte. A terme, cela pourrait être rédhibitoire :

(Extrait) Warning: If your project is one that will undergo any form of security review, using innerHTML most likely will result in your code being rejected. For example, if you use innerHTML in a browser extension and submit the extension to addons.mozilla.org, it will not pass the automated review process.

Ainsi voici ce qui ne faut pas faire :

var p = document.createElement("p"); 
p.innerHTML = "<i>coucou</i>";

Voici ce qui est souhaitable :

→ soit prendre un gabarit template dans votre code source avec querySelector, et utiliser .textContent pour ajouter votre contenu texte. Vous pouvez également utiliser la fonction DOMParser qui vous retournera un document utilisable ;

→ soit créer de toute pièce le paragraphe et le balisage italique en Javascript, avant d’insérer le contenu là aussi avec .textContent.

Dans notre fichier d’arrière-plan background.js, nous avons utilisé les écouteurs d’événements pour intercepter les requêtes HTTP en fonction du type (main_frame pour notre cas) et de pattern matching, c’est-à-dire d’une correspondance de motif des URL.

browser.webRequest.onBeforeRequest.addListener( 
    listener,
    {    
        urls: browser.SurveilleURLs, 
        types: [ 
            "main_frame" 
        ] 
    }, 
    [ 
        "blocking" 
    ] 
);

Cet écouteur renvoie en outre à une fonction listener créée de toute pièce pour l’occasion. Afin d’accéder à notre page d’édition, nous utiliserons le même principe. À cette différence que nous allons écouter le clic sur un bouton ajouté à l’interface du navigateur. Commençons par ajouter à notre fichier manifest le bloc suivant, avec un fichier de logo « qui va bien » à la racine de notre WebExt :

"browser_action": { 
    "default_icon": { 
      "19": "logo.png"  
    }, 
    "default_title": "Editeur de transformations" 
  }

Magie : le bouton apparaît ! Il ne reste plus dans notre fichier d’arrière-plan qu’à ajouter un écouteur adapté :

browser.browserAction.onClicked.addListener( 
  () => { 
    browser.tabs.create( 
      {
        url: browser.extension.getURL( 
          "edition.html" 
        ) 
      } 
    ).then( 
      (objTab) => { 
        browser.tabs.executeScript( 
          objTab["id"], 
          { 
            "file" : browser.extension.getURL( 
              "edition.js" 
            ) 
          } 
        ); 
      } 
    ); 
  } 
);

Décomposons les deux étapes de cette portion de code : ouvrir un nouvel onglet vers la page edition.html, puis une fois cet onglet créé, nous utilisons son ID sur le navigateur pour y injecter un script JS : edition.js.

L’insertion étant faite lorsqu’une page est appelée – c’est-à-dire ici qu’un onglet est ouvert –, le rechargement simple, avec F5 par exemple, n’appellera pas le script à nouveau. Celui-ci n’étant pas connu sur la page, celle-ci restera inerte. Je vous encourage vivement à tester le code plus haut, même s’il ne remplit pas la fonction que l’on aurait pu initialement attendre. Ce cas se présente ici compte tenu de la spécificité de l’environnement (page interne à la WebExt).

Pour être chargé à chaque chargement du document, le script de notre page d’édition doit être appelé dans l’entête de la page d’édition et non pas dans le script d’arrière-plan…

<script type="text/javascript" src="./edition.js"></script>

Le script d’arrière-plan pour ce point, se limite désormais à :

browser.browserAction.onClicked.addListener( 
  () => { 
    browser.tabs.create( 
      {
        url: browser.extension.getURL( 
          "edition.html" 
        ) 
      } 
    ); 
}

Nouveau problème me direz-vous ? Comme nous appelons notre script dans la page, quelle sera la portée des variables ? Aura-t-on accès à la partie de l’API WebExt dédiée au script de contenu ? Hé bien oui : contre toute attente, c’est l’URL, pointant sur l’ID de la WebExt et sur un protocole « propriétaire » (moz-extension), qui permettra au navigateur d’autoriser le script devenu script de page à se comporter comme un script de contenu.

Faites le test :

console.log("browser", browser);

… renverra aussi bien l’objet browser dans le script d’arrière-plan insérant un script de contenu, que dans le script de page se comportant comme un script de contenu.

Nous pouvons donc intelligemment penser notre code pour réutiliser un peu partout les mêmes bibliothèques de procédures et de fonctions. Cependant nous devons désormais intercepter le chargement de la page : l’insertion du script en tant que de notre script de contenu en tant que script de page, arrive antérieurement à ce qu’aurait fait une insertion depuis l’arrière-plan de la WebExt.

Ainsi window.addEventListener sur l’événément load peut devenir impératif si vous souhaitez contrôler le déclenchement de certaines fonctions après le chargement complet de la page (DOM et contenus extérieurs).