# Document-Policy (/fr/docs/web-security/policies/document-policy) Document-Policy configure le comportement et les contraintes de fonctionnalités d'un document donné via des points de configuration nommés, par exemple l'activation de l'API JS Self-Profiling avec `js-profiling`. Contrairement à [Permissions-Policy](/fr/docs/web-security/policies/permissions-policy), elle n'est pas déléguée aux sous-frames de la même façon : c'est un ensemble de garde-fous par document. Document-Policy est un brouillon du Community Group WICG, pas un standard W3C, et n'est implémentée que dans Chromium, où la plupart des points de configuration sont derrière des flags ; seul `js-profiling` est activé par défaut. L'ensemble des points de configuration est défini par l'implémentation et peut changer, ne comptez donc pas sur une liste de directives figée. La configuration utilisable aujourd'hui active l'API JS Self-Profiling : ```http Document-Policy: js-profiling ``` ## Comment fonctionne Document-Policy [#comment-fonctionne-document-policy] Le header est un dictionnaire structured-field de points de configuration. Chaque point a une valeur typée : un booléen (`?0` désactivé, `?1` activé), un entier, un flottant ou une énumération. Chaque point gouverne un comportement du document. La liste des points existants est définie par le navigateur, pas par un registre standard figé. ## Comment configurer Document-Policy [#comment-configurer-document-policy] | Point de configuration | Statut | Effet | | ----------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------- | | `js-profiling` | 🧪 Expérimental | Active l'API JS Self-Profiling. Le seul point de configuration activé par défaut dans Chromium. | | `include-js-call-stacks-in-crash-reports` | 🧪 Expérimental | Conditionne l'inclusion des piles d'appels JavaScript dans les rapports de crash. | Document-Policy est un brouillon WICG, implémenté uniquement dans Chromium, et la plupart de ses points de configuration sont derrière des flags. Les deux points ci-dessus sont ceux qui valent la peine d'être connus aujourd'hui ; traitez toute liste plus longue comme instable, et vérifiez qu'un point fonctionne dans vos navigateurs cibles avant de vous y fier. ## Mode Report-Only [#mode-report-only] ```http Reporting-Endpoints: doc-endpoint="https://.report.centralcsp.com" ``` ```http Document-Policy-Report-Only: js-profiling;report-to=doc-endpoint ``` Chaque point peut porter un paramètre `report-to` ; `*;report-to=endpoint` définit un endpoint par défaut pour tous les points, et `report-to=none` désactive le reporting pour un point. Le brouillon définit `Document-Policy-Report-Only`, mais la livraison des rapports de bout en bout dans Chromium n'est pas confirmée, vérifiez donc que les rapports arrivent réellement avant de vous appuyer dessus. ## Ce contre quoi il protège [#ce-contre-quoi-il-protège] Aujourd'hui, moins que le nom ne le suggère. Les deux points de configuration utilisables encadrent des diagnostics plutôt que de bloquer des attaques : `js-profiling` contrôle si un document peut profiler son propre JavaScript, et `include-js-call-stacks-in-crash-reports` contrôle si les rapports de crash portent des piles d'appels. L'intérêt du header est d'activer ces fonctions délibérément, document par document. ## Configurations non sûres à éviter [#configurations-non-sûres-à-éviter] Laisser sans contrainte un point de configuration connu comme risqué vide le header de son intérêt, et, comme pour toute fonctionnalité de reporting, pointer `report-to` vers un hôte que vous ne contrôlez pas fait fuiter des données de rapport. Contraignez explicitement les points qui vous importent plutôt que de compter sur une valeur par défaut sûre. ## Contournements et limites connus [#contournements-et-limites-connus] Il n'existe pas de registre normatif des points de configuration, la prise en charge est limitée à Chromium, et la politique n'est pas déléguée aux sous-frames comme l'est Permissions-Policy : elle gouverne le document sur lequel elle est définie plutôt qu'un arbre de frames entier. ## Risques [#risques] Comme l'ensemble de fonctionnalités est instable, un point dont vous dépendez peut changer ou disparaître entre deux versions du navigateur. Gardez les contraintes en Report-Only quand vous le pouvez, et surveillez les rapports avant d'appliquer. ## Recommandation [#recommandation] ```http Document-Policy: js-profiling ``` Traitez Document-Policy comme expérimentale. N'adoptez que les deux points de configuration qui fonctionnent dans Chromium aujourd'hui, `js-profiling` et `include-js-call-stacks-in-crash-reports`, et seulement après des tests dans vos navigateurs cibles. Préférez `Document-Policy-Report-Only` là où il est disponible ; le brouillon le définit, mais la livraison de bout en bout dans Chromium n'est pas confirmée, vérifiez donc que les rapports arrivent avant de vous y fier. ## Reporting [#reporting] Un paramètre `report-to` par point route les violations de ce point vers un endpoint nommé, et le navigateur émet le [rapport document-policy-violation](/fr/docs/web-security/reporting-api/reports/document-policy-violation). Un point voisin, `include-js-call-stacks-in-crash-reports`, enrichit le [rapport crash](/fr/docs/web-security/reporting-api/reports/crash) avec une pile JS, comme l'explique [rapports de crash et de non-réponse du navigateur](/fr/blog/browser-crash-reports). CentralCSP collecte le [flux](/fr/docs/platform/monitoring/document-policy). ## Prise en charge par les navigateurs [#prise-en-charge-par-les-navigateurs] Navigateurs basés sur Chromium uniquement ; expérimental, sans registre normatif des points de configuration. ## Voir aussi [#voir-aussi] * [rapport document-policy-violation](/fr/docs/web-security/reporting-api/reports/document-policy-violation) * [Document-Policy expliqué (guide)](/fr/blog/document-policy-explained) * [rapport crash](/fr/docs/web-security/reporting-api/reports/crash) * [Header Reporting-Endpoints](/fr/docs/web-security/reporting-api/headers/reporting-endpoints) * [Surveillance Document-Policy dans CentralCSP](/fr/docs/platform/monitoring/document-policy) ## Sources [#sources] * [WICG, Document Policy](https://wicg.github.io/document-policy/)