declarativeNetRequest vs webRequest : ce qu’une extension VPN peut encore modifier

Dossier technique

Dans Manifest V3, le débat n’oppose pas une API “ancienne” à une API “moderne”. Il oppose deux modèles d’intervention différents sur les requêtes réseau. webRequest expose le cycle de vie des requêtes à l’extension. declarativeNetRequest fait exécuter au navigateur des règles déclarées à l’avance. Pour une extension VPN, cette différence change la lecture des capacités réelles, du niveau de visibilité sur le trafic, de la performance, et de ce qu’il est encore possible de modifier en pratique.

Une extension VPN de navigateur ne se réduit pas à un simple bouton “connect”. Si elle veut agir sur les requêtes du navigateur, elle doit s’appuyer soit sur le modèle webRequest, soit sur le modèle declarativeNetRequest, soit sur une combinaison réfléchie des deux. Le choix n’est pas purement stylistique. Il détermine si l’extension observe directement les événements réseau ou si elle délègue au navigateur l’application de règles définies à l’avance.

C’est pour cette raison qu’une extension VPN sérieuse ne doit jamais être évaluée uniquement sur son interface ou sa communication. Il faut regarder quel mécanisme elle utilise pour agir sur le trafic, quel niveau de contrôle il lui reste réellement en MV3, et quels compromis cela introduit en termes de visibilité, de surface de confiance et de maintenabilité.

Deux modèles d’intervention très différents

webRequest expose à l’extension le cycle de vie d’une requête : création, envoi, réception d’en-têtes, redirections, authentification, erreurs éventuelles. L’extension reçoit des événements et peut, selon ses permissions et le contexte d’exécution autorisé, observer ou influer sur ce cycle.

declarativeNetRequest, au contraire, ne demande pas à l’extension d’intercepter chaque requête pour décider quoi faire. L’extension déclare des règles ; c’est ensuite le navigateur qui les applique lui-même. Cette différence compte énormément pour une extension VPN : on passe d’un modèle d’inspection active à un modèle de politique déclarative.

Il ne faut donc pas poser la question “quelle API est meilleure ?”, mais “de quel niveau de visibilité et de modification l’extension a-t-elle réellement besoin ?”.

webRequest : observer le cycle de vie des requêtes

L’API webRequest existe toujours en Manifest V3. Elle n’a pas disparu. Ce qui a changé, c’est la disponibilité du mode bloquant pour la majorité des extensions. En MV3, la permission webRequestBlocking n’est plus accessible à la plupart des extensions classiques ; elle reste réservée aux extensions installées par policy.

Cela signifie qu’une extension VPN peut encore utiliser webRequest pour observer, corréler et analyser les requêtes, mais qu’elle ne bénéficie plus, dans le cas général, du même pouvoir synchrone de blocage ou de modification que dans l’ancien modèle MV2.

{
  "manifest_version": 3,
  "permissions": ["webRequest"],
  "host_permissions": ["*://*.example.com/*"]
}

Pour un usage donné, l’extension doit aussi disposer des host_permissions adaptés. Pour intercepter une sous-ressource, le périmètre doit couvrir l’URL demandée et son initiateur. C’est une différence de lecture importante : même l’observation n’est pas universelle par défaut.

declarativeNetRequest : déplacer la logique de décision dans le navigateur

Avec declarativeNetRequest, l’extension ne voit pas le contenu de chaque requête avant d’agir. Elle fournit des règles et laisse le navigateur les évaluer lui-même. Chrome présente explicitement ce modèle comme plus respectueux de la vie privée, précisément parce que l’extension n’a pas besoin d’intercepter et de lire les requêtes pour les bloquer ou les modifier.

Pour une extension VPN, cela a un intérêt évident : réduire la surface d’accès directe au trafic tout en conservant une capacité de blocage, de redirection, de mise à niveau ou de modification d’en-têtes dans certaines limites. Mais cela a aussi un coût : tout ce qui dépend d’une décision algorithmique riche, d’un contexte calculé dynamiquement ou d’une logique d’inspection fine devient plus difficile à exprimer.

{
  "manifest_version": 3,
  "permissions": ["declarativeNetRequest"],
  "declarative_net_request": {
    "rule_resources": [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }]
  }
}

En MV3, le vrai basculement concerne le mode bloquant

Le point structurant n’est pas l’existence de webRequest, mais la disparition de webRequestBlocking pour la plupart des extensions Manifest V3. En pratique, cela pousse la majorité des extensions réseau vers declarativeNetRequest lorsqu’elles veulent encore bloquer, rediriger ou modifier des requêtes sans disposer d’une installation par policy.

Il faut être précis ici : dire que webRequest est “mort” serait faux. Dire que declarativeNetRequest a tout remplacé serait faux aussi. Le bon diagnostic est plus technique : en MV3, le pouvoir de transformation synchrone de la requête a été déplacé, pour le cas général, vers une logique déclarative évaluée par le navigateur lui-même.

Les permissions d’hôte ne jouent pas le même rôle selon l’action

Une subtilité importante mérite d’être retenue. Avec declarativeNetRequest, toutes les actions ne demandent pas le même niveau d’accès. Le blocage et l’upgrade de requêtes peuvent être effectués sans host_permissions larges, alors que la redirection et certaines modifications d’en-têtes exigent des permissions d’hôte adaptées pour l’URL visée, ainsi que, hors navigation principale, pour l’initiateur de la requête.

Cette distinction est précieuse pour auditer une extension VPN. Une extension peut donc se présenter comme plus sobre, non parce qu’elle renonce à toute action réseau, mais parce qu’elle choisit un sous-ensemble d’actions déclaratives moins invasif du point de vue des permissions.

C’est aussi la raison pour laquelle il faut lire cette page en parallèle avec Permissions et host_permissions.

Ce que declarativeNetRequest peut faire en pratique

Le cœur de declarativeNetRequest repose sur des règles et des actions. Parmi les actions principales, on retrouve le blocage, l’autorisation, l’upgrade d’URL et, selon les cas, la redirection ou la modification d’en-têtes. Ce modèle est particulièrement adapté à des politiques réseau répétables, stables et suffisamment simples pour être exprimées sous forme déclarative.

Pour une extension VPN, cela peut servir à :

• bloquer certains endpoints incompatibles avec une politique de confidentialité ;
• empêcher des fuites évidentes vers des domaines connus ;
• appliquer une logique de redirection vers des ressources contrôlées ;
• ajuster certains en-têtes dans un cadre borné ;
• faire respecter une politique de filtrage sans exposer chaque requête à l’extension.

Le point important n’est pas d’idéaliser DNR, mais de comprendre qu’il fonctionne très bien lorsqu’une politique peut être décrite à l’avance.

Règles statiques, dynamiques et de session : trois couches, trois usages

declarativeNetRequest ne se réduit pas à un unique fichier de règles. Le modèle distingue généralement des règles statiques, des règles dynamiques et des règles de session.

• Règles statiques : empaquetées avec l’extension, prévisibles, faciles à auditer.
• Règles dynamiques : modifiables par l’extension à l’exécution, persistantes au-delà de la session.
• Règles de session : valables pour la session en cours, utiles pour des ajustements temporaires.

Pour une extension VPN, cette hiérarchie n’est pas cosmétique. Elle permet de distinguer ce qui relève de la politique stable du produit, ce qui relève d’un ajustement persistant du comportement, et ce qui relève d’un changement temporaire. Une extension techniquement disciplinée devrait laisser cette séparation apparaître clairement.

La logique de priorité compte autant que la règle elle-même

Une politique déclarative n’est pas simplement une liste. Le moteur DNR évalue des règles qui peuvent entrer en concurrence. Priorité, type d’action, étapes d’évaluation et exceptions jouent donc un rôle central. Une extension VPN qui empile des règles sans hiérarchie claire risque de produire un système opaque, difficile à relire et encore plus difficile à auditer.

Il faut ici penser comme sur un firewall applicatif : une règle n’a de sens que dans l’ordre logique et le contexte d’évaluation où elle s’insère. Une politique déclarative mal ordonnée ne devient pas plus sûre simplement parce qu’elle est “déclarative”.

Le matching sur les en-têtes de réponse change la portée de certaines règles

Depuis Chrome 128, declarativeNetRequest prend en charge le matching sur certains en-têtes de réponse via des champs comme responseHeaders et excludedResponseHeaders. Ce point est important parce qu’il déplace certaines décisions à un moment plus tardif du cycle de la requête.

Il faut être très précis : une règle qui dépend des en-têtes de réponse s’applique une fois que le serveur a déjà répondu. Cela signifie qu’un blocage ou une redirection à ce stade n’empêche pas le contact initial avec le serveur. Pour un site technique, ce détail n’est pas secondaire. Il change l’interprétation réelle du verbe “bloquer”.

Autrement dit, toutes les règles DNR n’agissent pas au même moment, et donc pas avec le même effet.

Ce que webRequest permet encore de faire utilement

Même en MV3, webRequest reste précieux dès qu’il faut observer, corréler ou diagnostiquer le cycle de vie des requêtes. L’API expose une séquence d’événements liée aux étapes du trafic réseau, et conserve donc une valeur forte pour la télémétrie locale, le débogage, l’inspection de comportements anormaux et certaines décisions indirectes qui n’exigent pas de bloquer en ligne.

En clair, webRequest reste la bonne couche pour comprendre ce qui se passe. declarativeNetRequest devient souvent la bonne couche pour faire appliquer au navigateur une politique pré-déclarée.

Il ne faut donc pas les opposer de manière caricaturale. Une extension VPN mature peut observer avec webRequest et agir, quand c’est pertinent, avec declarativeNetRequest.

declarativeNetRequestFeedback : le débogage n’est pas gratuit

Le modèle déclaratif réduit la visibilité directe de l’extension sur les requêtes qu’elle influence. Chrome et MDN prévoient donc une permission spécifique, declarativeNetRequestFeedback, pour des fonctions de débogage comme getMatchedRules() ou onRuleMatchedDebug.

Ce point est très révélateur : une politique déclarative est plus discrète du point de vue de l’accès au trafic, mais elle rend aussi le diagnostic moins immédiat. Une extension VPN qui s’appuie fortement sur DNR doit donc compenser par une instrumentation d’audit sérieuse, faute de quoi elle risque de devenir opaque même pour son propre éditeur.

Modifier les corps de réponse n’entre pas dans la promesse normale de DNR

Il faut rappeler une limite importante. Le modèle declarativeNetRequest agit sur les requêtes et certains en-têtes, mais il n’offre pas un équivalent général à l’inspection et à la transformation du corps des réponses telle qu’on la conçoit via d’autres mécanismes plus intrusifs.

Cette différence compte pour les extensions qui voudraient faire de la transformation profonde, du rewriting riche ou des logiques qui dépendent du contenu lui-même. Une extension VPN n’a généralement pas besoin d’aller aussi loin, mais ce point reste essentiel pour ne pas surinterpréter les capacités du modèle déclaratif.

Le cas particulier des extensions installées par policy

Une exception existe : les extensions installées par policy peuvent encore accéder à webRequestBlocking. Ce détail ne concerne pas le grand public, mais il compte pour un site technique. Il rappelle que le modèle MV3 n’efface pas totalement l’ancien pouvoir de blocage synchrone ; il le réserve à des contextes administrés.

Pour une extension VPN destinée à un parc géré en entreprise, la lecture de la capacité réelle n’est donc pas forcément identique à celle d’une extension grand public distribuée classiquement.

Comment lire une extension VPN à la lumière de ces deux APIs

La bonne lecture consiste à poser quatre questions :

• l’extension observe-t-elle le trafic ou délègue-t-elle l’essentiel au navigateur ;
• a-t-elle encore besoin d’une logique d’interception riche, ou seulement d’une politique de règles ;
• sa promesse de confidentialité est-elle cohérente avec le niveau réel d’accès aux requêtes ;
• le choix technique améliore-t-il la lisibilité du produit, ou masque-t-il une architecture confuse.

Une extension VPN techniquement sobre tendra à minimiser l’observation directe quand une règle déclarative suffit. Une extension plus ambitieuse dans l’analyse du trafic devra justifier pourquoi elle garde webRequest au cœur de sa logique.

Ce qu’il faut auditer concrètement

• L’extension utilise-t-elle webRequest, declarativeNetRequest, ou les deux ?
• Le choix technique est-il cohérent avec la promesse fonctionnelle du produit ?
• Les actions déclaratives sont-elles suffisantes, ou l’éditeur compense-t-il maladroitement des limites du modèle ?
• Les host_permissions demandées sont-elles proportionnées aux actions réellement utilisées ?
• Les règles sont-elles lisibles, hiérarchisées et séparées entre statique, dynamique et session ?
• La documentation traite-t-elle sérieusement les limites du modèle déclaratif ?
• Le produit dépend-il d’un cas particulier de type policy-installed pour tenir ses promesses ?
• L’extension privilégie-t-elle une logique de politique réseau claire plutôt qu’un empilement opaque de règles ?

La suite logique est de relier cette lecture à Manifest V3 et service workers pour le modèle d’exécution, puis à la méthode d’audit complète pour l’évaluation finale.

Conclusion

En Manifest V3, une extension VPN ne modifie plus les requêtes dans le même cadre qu’en MV2. webRequest conserve une valeur d’observation et d’analyse, mais la modification synchronisée en ligne est largement sortie du modèle grand public. declarativeNetRequest devient donc la couche centrale pour appliquer des politiques réseau déclaratives, avec un meilleur contrôle du point de vue du navigateur, mais avec une expressivité différente. Ce n’est pas une simple évolution d’API. C’est un changement de philosophie de contrôle.