From 9a34954429297590f602b980c7a6c59afc0cf9c7 Mon Sep 17 00:00:00 2001
From: Kevin McNee <mcnee@chromium.org>
Date: Tue, 8 Nov 2022 18:38:13 -0500
Subject: [PATCH] Add explainer for the referrer_policy key in speculation
 rules (#205)

---
 fetch.md    |  2 +-
 triggers.md | 24 ++++++++++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/fetch.md b/fetch.md
index 3d8572f..9ebbb9b 100644
--- a/fetch.md
+++ b/fetch.md
@@ -113,7 +113,7 @@ One alternative to our sufficiently-strict referrer policy proposal above is to
 
 This would allow pages which otherwise set globally-lax referrer policies, such as `"unsafe-url"`, to perform cross-site preloads. Whereas with our current proposal, such preload requests are ignored.
 
-The main downside of this is that deviates from developer intent. We think it's better to instead [introduce the ability to trigger preloads with a different referrer policy than your document uses](https://github.com/WICG/nav-speculation/issues/167).
+The main downside of this is that deviates from developer intent. We think it's better to instead [introduce the ability to trigger preloads with a different referrer policy than your document uses](./triggers.md#explicit-referrer-policy). See [discussion](https://github.com/WICG/nav-speculation/issues/167).
 
 ## Using a privacy-preserving proxy
 
diff --git a/triggers.md b/triggers.md
index 8dfcad2..3d48dd0 100644
--- a/triggers.md
+++ b/triggers.md
@@ -14,6 +14,7 @@
   - [List rules](#list-rules)
   - [Requirements](#requirements)
   - [Window name targeting hints](#window-name-targeting-hints)
+  - [Explicit referrer policy](#explicit-referrer-policy)
 - [Future extensions](#future-extensions)
   - [Scores](#scores)
   - [Document rules](#document-rules)
@@ -177,6 +178,29 @@ Note that if a page is truly unsure whether a given URL will be prerendered into
 
 However, in implementations such as Chromium that need the target hint, this will prerender the page twice, and thus use twice as many resources. So this is best avoided if possible.
 
+### Explicit referrer policy
+
+By default, the referring document's referrer policy is used for the speculative request. The policy to use for the speculative request can be specified in a rule using the `"referrer_policy"` key and the desired referrer policy string.
+
+For example:
+```json
+{
+  "prefetch": [
+    {"source": "list",
+     "urls": ["https://en.wikipedia.org/wiki/Lethe"],
+     "referrer_policy": "no-referrer"
+    }
+  ]
+}
+```
+
+For speculation actions that would be prevented by the [**sufficiently-strict referrer policy** requirement](./fetch.md#stripping-referrer-information) on a referring page with a lax policy, this allows the referring page to set a stricter policy specifically for the speculative request.
+
+Note that referrer policy matching is not done between the speculative request and the user facing navigation. So given the above rule, a request would be made with `no-referrer` and would still be used even if the user clicked on:
+```html
+<a href="https://en.wikipedia.org/wiki/Lethe" referrerpolicy="unsafe-url">
+```
+
 ## Future extensions
 
 ### Scores