From a98885a27bfdf27e96bab2e0effb9fe5b13000a1 Mon Sep 17 00:00:00 2001
From: Douglas Creager <dcreager@dcreager.net>
Date: Wed, 27 Jun 2018 09:52:27 -0400
Subject: [PATCH] Collect current User-Agent when queueing a report (#96)

This lets us detect when the browser uses a non-default User-Agent
to request a page (e.g. for the "request desktop page" feature).

Closes #52
---
 index.src.html | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/index.src.html b/index.src.html
index 6a1eec9..3260ac6 100644
--- a/index.src.html
+++ b/index.src.html
@@ -77,6 +77,9 @@ <h1>Reporting API</h1>
     type: dfn
       text: origin
       text: top-level browsing context
+  urlPrefix: system-state.html
+    type: dfn
+      text: navigator.userAgent; url: dom-navigator-useragent
 spec: RFC3986; urlPrefix: https://tools.ietf.org/html/rfc3986
   type: grammar
     text: absolute-uri; url: section-4.3
@@ -333,6 +336,17 @@ <h3 id="concept-reports">Reports</h3>
   Each <a>report</a> has an <dfn for="report" export>origin</dfn>,
   which is an <a spec="html">origin</a> representing the report's initiator.
 
+  Each <a>report</a> has a <dfn for="report" export>user agent</dfn>, which is
+  the value of the <code>User-Agent</code> <a>header</a> of the <a>request</a>
+  from which the report was generated.
+
+  Note: The <a for="report">user agent</a> of a <a>report</a> represents the
+  <code>User-Agent</code> sent by the browser for the page which generated the
+  <a>report</a>.  This is potentially distinct from the <code>User-Agent</code>
+  sent in the HTTP headers when uploading the report to a collector — for
+  instance, where the browser has chosen to use a non-default
+  <code>User-Agent</code> string such as the "request desktop site" feature.
+
   Each <a>report</a> has a <dfn for="report" export>group</dfn>,
   which is a string representing the {{endpoint group/name}} of the
   <a spec="html">origin</a>'s <a>endpoint group</a> that the report will be sent
@@ -639,6 +653,8 @@ <h3 id="queue-report" algorithm>
       ::  |data|
       :   [=report/origin=]
       ::  |settings|'s <a spec="html">origin</a>
+      :   [=report/user agent=]
+      ::  The current value of <a><code>navigator.userAgent</code></a>
       :   [=report/group=]
       ::  |endpoint group|
       :   [=report/type=]
@@ -847,6 +863,8 @@ <h3 id="try-delivery" algorithm>
           ::  |report|'s [=report/type=]
           :   `url`
           ::  |report|'s [=report/url=]
+          :   `user_agent`
+          ::  |report|'s [=report/user agent=]
           :   `body`
           ::  |report|'s [=report/body=]
 
@@ -1247,6 +1265,7 @@ <h2 id="sample-reports">Sample Reports</h2>
         "type": "csp",
         "age": 10,
         "url": "https://example.com/vulnerable-page/",
+        "user_agent": "ReportingSpec/1",
         "body": {
           "blocked": "https://evil.com/evil.js",
           "directive": "script-src",
@@ -1258,6 +1277,7 @@ <h2 id="sample-reports">Sample Reports</h2>
         "type": "hpkp",
         "age": 32,
         "url": "https://www.example.com/",
+        "user_agent": "ReportingSpec/1",
         "body": {
           "date-time": "2014-04-06T13:00:50Z",
           "hostname": "www.example.com",
@@ -1279,6 +1299,7 @@ <h2 id="sample-reports">Sample Reports</h2>
         "type": "nel",
         "age": 29,
         "url": "https://example.com/thing.js",
+        "user_agent": "ReportingSpec/1",
         "body": {
           "referrer": "https://www.example.com/",
           "server-ip": "234.233.232.231",