← Tous les articles

Configurer les fonctionnalités par document avec Document-Policy

CentralCSP Team ·

Dernière mise à jour:

Le header Document-Policy vous permet d'activer ou de désactiver des fonctionnalités et des contraintes au niveau du document pour une seule page, par exemple couper document.write, exiger que les images déclarent leurs dimensions, ou bloquer les XHR synchrones. Le navigateur applique la contrainte et, si vous le lui demandez, envoie un report document-policy-violation quand la page en franchit une. Cet article couvre ce que le header configure, la variante report-only pour mesurer avant d'imposer, et comment les reports de violation vous parviennent via la Reporting API.

Disponibilité limitée

Document-Policy est un brouillon de Community Group WICG, pas un standard W3C finalisé. Seuls les navigateurs basés sur Chromium l'implémentent ; Firefox et Safari n'implémentent pas du tout Document-Policy. Même dans Chromium, la plupart des points de configuration sont expérimentaux. Traitez les listes ci-dessous comme spécifiques à Chromium et confirmez qu'un point est réellement utilisable avant de vous y fier.

Ce que Document-Policy configure

Le header est une liste de points de configuration, chacun régissant un seul comportement du document. Un point prend une valeur typée : un booléen (?0 pour off, ?1 pour on), un entier, un flottant ou un enum. Quels points existent est décidé par le navigateur, pas par un registre figé, donc le geste pratique est de définir explicitement ceux qui vous intéressent et de surveiller les reports.

Les points sur lesquels vous pouvez vous fier dépendent entièrement du navigateur. Dans Chromium, deux sont utilisables en navigation normale :

  • js-profiling active l'API JS Self-Profiling, permettant à une page d'échantillonner son propre JavaScript pour profiler la performance en conditions réelles en production.
  • include-js-call-stacks-in-crash-reports=?1 enrichit un report de crash du navigateur avec une pile d'appels JavaScript, pour qu'un crash pointe vers le code qui l'a causé.

Plusieurs autres points sont définis dans le brouillon mais expérimentaux. Ils n'existent que dans Chromium et ne prennent effet que derrière le flag chrome://flags/#enable-experimental-web-platform-features, donc vous ne pouvez pas encore compter dessus pour de vrais utilisateurs :

  • document-write=?0 coupe document.write, un danger d'injection de script et de rendu qui bloque le parseur.
  • unsized-media=?0 exige que les éléments média déclarent une taille, ce qui évite le décalage de mise en page qu'une image sans taille provoque.
  • oversized-images plafonne à quel point la taille intrinsèque d'une image peut dépasser sa taille affichée, pour qu'une page ne puisse pas livrer une image de plusieurs mégaoctets réduite en CSS.
  • sync-xhr=?0 bloque XMLHttpRequest synchrone, qui gèle le thread principal.

Un exemple minimal, utilisant le point expérimental document-write pour montrer la syntaxe du header :

Document-Policy: document-write=?0

Pour le traitement complet et sourcé de comment le header se parse et ce que chaque point signifie, voyez la référence Document-Policy.

La variante report-only

Document-Policy-Report-Only évalue les mêmes contraintes et signale ce qui casserait, sans rien imposer réellement. Cela compte ici plus que pour la plupart des headers, parce que l'ensemble des points de configuration dépend de l'implémentation : vous voulez confirmer ce qui se déclenche réellement dans les navigateurs de vos utilisateurs avant de le bloquer.

Utilisez-le comme vous utiliseriez le header imposant, mais pointez chaque point contraint vers un endpoint de reporting. Déclarez d'abord l'endpoint avec Reporting-Endpoints :

Reporting-Endpoints: doc-endpoint="https://<Endpoint-ID>.report.centralcsp.com"

Puis définissez la politique report-only et routez le point vers cet endpoint :

Document-Policy-Report-Only: document-write=?0;report-to=doc-endpoint

Chaque point peut porter son propre paramètre report-to. Un *;report-to=endpoint en tête définit un endpoint par défaut pour chaque point, et report-to=none désactive le reporting pour un point précis. Une fois que le flux de reports devient silencieux pour une contrainte, vous pouvez la déplacer du header report-only vers le header Document-Policy imposant.

Le report document-policy-violation

Quand la page fait quelque chose qu'une contrainte interdit, le navigateur envoie un report document-policy-violation à l'endpoint que vous avez nommé. Il vous dit quel point a été violé et où, pour que vous trouviez le code derrière.

{
  "type": "document-policy-violation",
  "age": 420,
  "url": "https://api-next.centralcsp.com/",
  "user_agent": "Mozilla/5.0 ...",
  "body": {
    "policyId": "document-write",
    "disposition": "report",
    "message": "Document policy violation: document-write is not allowed.",
    "sourceFile": "https://api-next.centralcsp.com/script.js",
    "lineNumber": 11,
    "columnNumber": 12
  }
}

Le policyId nomme le point de configuration, disposition vaut report en mode report-only et enforce une fois que vous imposez, et sourceFile avec la ligne et la colonne pointe directement vers le code fautif. Un piège à prévoir : le report reçu à votre endpoint nomme le champ policyId, mais l'interface JS ReportingObserver dans le navigateur expose la même valeur sous featureId, donc attendez-vous à ce que le nom de l'API JS diffère du champ transmis. La charge complète et la référence des champs sont sur la page du report document-policy-violation.

Collectez les reports sans backend

Un report document-policy-violation utilise le même chemin de livraison que vos autres reports de navigateur, donc il arrive dans le même flux que vos reports CSP, NEL et de crash. Pointez l'endpoint report-to vers CentralCSP et les reports document-policy atterrissent à côté du reste, mis en graphiques et cherchables, sans avoir besoin d'un pipeline séparé pour une fonctionnalité expérimentale. C'est aussi là que le signal report-only devient utile : vous pouvez mesurer ce qu'une contrainte casserait sur du trafic réel avant de l'imposer.

Les violations de Document Policy groupées par fonctionnalité, avec des lignes document-write et unsized-media et leurs dispositions

Étapes suivantes

Collectez les reports Document-Policy depuis de vrais navigateurs.

Sources

Articles liés