← 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 enfreint 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 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. C'est le navigateur, et non un registre figé, qui décide des points disponibles : en pratique, définissez explicitement ceux qui vous intéressent et surveillez les reports.

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

  • js-profiling active l'API JS Self-Profiling, qui permet à une page d'échantillonner son propre JavaScript pour mesurer ses performances 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 restent expérimentaux. Ils n'existent que dans Chromium et ne prennent effet que derrière le flag chrome://flags/#enable-experimental-web-platform-features, vous ne pouvez donc pas encore compter dessus face à de vrais utilisateurs :

  • document-write=?0 coupe document.write, à la fois un risque d'injection de script et un 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 provoqué par une image sans dimensions.
  • oversized-images limite l'écart entre la taille intrinsèque d'une image et 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, avec le point expérimental document-write, pour montrer la syntaxe du header :

Document-Policy: document-write=?0

Pour le détail complet et sourcé du parsing du header et du sens de chaque point, 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 : mieux vaut confirmer ce qui se déclenche réellement dans les navigateurs de vos utilisateurs avant de bloquer quoi que ce soit.

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 qu'une contrainte ne génère plus aucun report, vous pouvez la faire passer du header report-only au 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ù, de quoi remonter au code responsable.

{
  "type": "document-policy-violation",
  "age": 420,
  "url": "https://example.com/",
  "user_agent": "Mozilla/5.0 ...",
  "body": {
    "policyId": "document-write",
    "disposition": "report",
    "message": "Document policy violation: document-write is not allowed.",
    "sourceFile": "https://example.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 utile 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 et de crash. Pointez l'endpoint report-to vers CentralCSP et les reports document-policy atterrissent à côté du reste, mis en graphiques et interrogeables, sans pipeline dédié à 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