Propagate referrer to new windows (#12397)

* Propagate referrer to new windows

Fixes #9205

* Rearrange -new-window event arguments for backwards-compatibility

* Plumb referrer policy through guest-window-manager

* Document the Referrer structure and its uses

* Add tests for referrer in new windows

* Docs nits

spec/api-web-contents-spec.js

@@ -708,4 +708,50 @@ describe('webContents module', () => {
       w.loadURL(`file://${fixtures}/pages/a.html`)
     })
   })
+
+  describe('referrer', () => {
+    it('propagates referrer information to new target=_blank windows', (done) => {
+      const server = http.createServer((req, res) => {
+        if (req.url === '/should_have_referrer') {
+          assert.equal(req.headers.referer, 'http://127.0.0.1:' + server.address().port + '/')
+          return done()
+        }
+        res.end('<a id="a" href="/should_have_referrer" target="_blank">link</a>')
+      })
+      server.listen(0, '127.0.0.1', () => {
+        const url = 'http://127.0.0.1:' + server.address().port + '/'
+        w.webContents.once('did-finish-load', () => {
+          w.webContents.once('new-window', (event, newUrl, frameName, disposition, options, features, referrer) => {
+            assert.equal(referrer.url, url)
+            assert.equal(referrer.policy, 'no-referrer-when-downgrade')
+          })
+          w.webContents.executeJavaScript('a.click()')
+        })
+        w.loadURL(url)
+      })
+    })
+
+    // TODO(jeremy): window.open() in a real browser passes the referrer, but
+    // our hacked-up window.open() shim doesn't. It should.
+    xit('propagates referrer information to windows opened with window.open', (done) => {
+      const server = http.createServer((req, res) => {
+        if (req.url === '/should_have_referrer') {
+          assert.equal(req.headers.referer, 'http://127.0.0.1:' + server.address().port + '/')
+          return done()
+        }
+        res.end('')
+      })
+      server.listen(0, '127.0.0.1', () => {
+        const url = 'http://127.0.0.1:' + server.address().port + '/'
+        w.webContents.once('did-finish-load', () => {
+          w.webContents.once('new-window', (event, newUrl, frameName, disposition, options, features, referrer) => {
+            assert.equal(referrer.url, url)
+            assert.equal(referrer.policy, 'no-referrer-when-downgrade')
+          })
+          w.webContents.executeJavaScript('window.open(location.href + "should_have_referrer")')
+        })
+        w.loadURL(url)
+      })
+    })
+  })
 })