From a7f850cb8b26f574f42050825f08c77de04a10f2 Mon Sep 17 00:00:00 2001
From: Pierre Le Fevre <hello@pierrelf.com>
Date: Sat, 28 Mar 2026 16:14:54 +0100
Subject: [PATCH] Implement Referrer Policy: parsing, computation, and
 integration

Add W3C Referrer Policy support with all 8 policies: no-referrer,
no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin,
strict-origin, strict-origin-when-cross-origin (default), and unsafe-url.

- New crates/net/src/referrer.rs: ReferrerPolicy enum, header/attribute
  parsing, and compute_referrer() for Referer header computation
- ResourceLoader: tracks document URL and referrer policy, sets Referer
  header on all outgoing requests, updates policy from Referrer-Policy
  response headers
- HTML integration: extracts <meta name="referrer"> from DOM, reads
  referrerpolicy attribute on <script>, <link>, and <img> elements
- Element-level policy overrides document-level policy per spec
- Strips fragment and userinfo from referrer URLs
- HTTPS-to-HTTP downgrade correctly handled for strict/downgrade policies

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 crates/browser/src/css_loader.rs    |  53 ++-
 crates/browser/src/img_loader.rs    |  17 +-
 crates/browser/src/loader.rs        | 120 ++++-
 crates/browser/src/main.rs          |  48 +-
 crates/browser/src/script_loader.rs |  24 +-
 crates/net/src/lib.rs               |   3 +-
 crates/net/src/referrer.rs          | 691 ++++++++++++++++++++++++++++
 7 files changed, 935 insertions(+), 21 deletions(-)
 create mode 100644 crates/net/src/referrer.rs

diff --git a/crates/browser/src/css_loader.rs b/crates/browser/src/css_loader.rs
index 177aed4..4c8ebaa 100644
--- a/crates/browser/src/css_loader.rs
+++ b/crates/browser/src/css_loader.rs
@@ -6,6 +6,7 @@
 
 use we_css::parser::{ImportRule, Parser, Rule, Stylesheet};
 use we_dom::{Document, NodeData, NodeId};
+use we_net::referrer::ReferrerPolicy;
 use we_url::{Origin, Url};
 
 use crate::loader::{LoadError, Resource, ResourceLoader, ResourceRequestType};
@@ -73,11 +74,22 @@ pub fn collect_stylesheets_with_origin(
                 let resolved = resolve_imports(sheet, loader, base_url, document_origin, 0);
                 all_rules.extend(resolved.rules);
             }
-            StyleSource::ExternalLink { href, media } => {
+            StyleSource::ExternalLink {
+                href,
+                media,
+                referrer_policy,
+            } => {
                 if !media_matches(&media) {
                     continue;
                 }
-                match fetch_stylesheet(loader, &href, base_url, document_origin, 0) {
+                match fetch_stylesheet_with_policy(
+                    loader,
+                    &href,
+                    base_url,
+                    document_origin,
+                    0,
+                    referrer_policy,
+                ) {
                     Ok(sheet) => all_rules.extend(sheet.rules),
                     Err(_) => {
                         // Graceful degradation: skip failed stylesheet loads.
@@ -109,7 +121,11 @@ enum StyleSource {
     /// A `<style>` element with inline CSS text.
     InlineStyle(String),
     /// A `<link rel="stylesheet">` element with an `href`.
-    ExternalLink { href: String, media: Option<String> },
+    ExternalLink {
+        href: String,
+        media: Option<String>,
+        referrer_policy: Option<ReferrerPolicy>,
+    },
     /// Not a stylesheet source.
     NotStylesheet,
 }
@@ -150,9 +166,13 @@ fn classify_style_node(doc: &Document, node: NodeId) -> StyleSource {
         match doc.get_attribute(node, "href") {
             Some(href) if !href.is_empty() => {
                 let media = doc.get_attribute(node, "media").map(|m| m.to_string());
+                let referrer_policy = doc
+                    .get_attribute(node, "referrerpolicy")
+                    .and_then(ReferrerPolicy::parse);
                 StyleSource::ExternalLink {
                     href: href.to_string(),
                     media,
+                    referrer_policy,
                 }
             }
             _ => StyleSource::NotStylesheet,
@@ -202,11 +222,28 @@ fn fetch_stylesheet(
     document_origin: &Origin,
     depth: usize,
 ) -> Result<Stylesheet, CssLoadError> {
-    let resource = loader.fetch_url_subresource(
-        href,
-        Some(base_url),
+    fetch_stylesheet_with_policy(loader, href, base_url, document_origin, depth, None)
+}
+
+/// Fetch an external stylesheet with optional element-level referrer policy override.
+fn fetch_stylesheet_with_policy(
+    loader: &mut ResourceLoader,
+    href: &str,
+    base_url: &Url,
+    document_origin: &Origin,
+    depth: usize,
+    element_policy: Option<ReferrerPolicy>,
+) -> Result<Stylesheet, CssLoadError> {
+    let url = we_url::Url::parse_with_base(href, base_url)
+        .or_else(|_| we_url::Url::parse(href))
+        .map_err(|_| CssLoadError::NotCss {
+            url: href.to_string(),
+        })?;
+    let resource = loader.fetch_subresource_with_referrer_policy(
+        &url,
         document_origin,
         ResourceRequestType::Stylesheet,
+        element_policy,
     )?;
 
     let (css_text, resolved_url) = match resource {
@@ -435,7 +472,7 @@ mod tests {
         let mut nodes = Vec::new();
         collect_style_nodes(&doc, doc.root(), &mut nodes);
         match classify_style_node(&doc, nodes[0]) {
-            StyleSource::ExternalLink { href, media } => {
+            StyleSource::ExternalLink { href, media, .. } => {
                 assert_eq!(href, "style.css");
                 assert!(media.is_none());
             }
@@ -455,7 +492,7 @@ mod tests {
         doc.append_child(root, link);
 
         match classify_style_node(&doc, link) {
-            StyleSource::ExternalLink { href, media } => {
+            StyleSource::ExternalLink { href, media, .. } => {
                 assert_eq!(href, "screen.css");
                 assert_eq!(media.as_deref(), Some("screen"));
             }
diff --git a/crates/browser/src/img_loader.rs b/crates/browser/src/img_loader.rs
index 4bcc56e..86b81b4 100644
--- a/crates/browser/src/img_loader.rs
+++ b/crates/browser/src/img_loader.rs
@@ -11,6 +11,7 @@ use we_image::gif::decode_gif;
 use we_image::jpeg::decode_jpeg;
 use we_image::pixel::{Image, ImageError};
 use we_image::png::decode_png;
+use we_net::referrer::ReferrerPolicy;
 use we_url::Url;
 
 use crate::loader::{LoadError, Resource, ResourceLoader};
@@ -121,8 +122,11 @@ pub fn collect_images(doc: &Document, loader: &mut ResourceLoader, base_url: &Ur
         let alt = doc.get_attribute(node, "alt").unwrap_or("").to_string();
         let attr_width = parse_dimension_attr(doc.get_attribute(node, "width"));
         let attr_height = parse_dimension_attr(doc.get_attribute(node, "height"));
+        let element_policy = doc
+            .get_attribute(node, "referrerpolicy")
+            .and_then(ReferrerPolicy::parse);
 
-        match fetch_and_decode(loader, &src, base_url) {
+        match fetch_and_decode(loader, &src, base_url, element_policy) {
             Ok(image) => {
                 let intrinsic_w = image.width as f32;
                 let intrinsic_h = image.height as f32;
@@ -220,8 +224,17 @@ fn fetch_and_decode(
     loader: &mut ResourceLoader,
     src: &str,
     base_url: &Url,
+    element_policy: Option<ReferrerPolicy>,
 ) -> Result<Image, ImgLoadError> {
-    let resource = loader.fetch_url(src, Some(base_url))?;
+    // Temporarily override the referrer policy if an element-level policy is set.
+    let saved_policy = loader.referrer_policy();
+    if let Some(policy) = element_policy {
+        loader.set_referrer_policy(policy);
+    }
+    let resource = loader.fetch_url(src, Some(base_url));
+    // Restore the document-level policy.
+    loader.set_referrer_policy(saved_policy);
+    let resource = resource?;
 
     let (data, url_str) = match resource {
         Resource::Image { data, url, .. } => (data, url.to_string()),
diff --git a/crates/browser/src/loader.rs b/crates/browser/src/loader.rs
index d653d02..9db666e 100644
--- a/crates/browser/src/loader.rs
+++ b/crates/browser/src/loader.rs
@@ -13,7 +13,8 @@ use we_net::cors::{
     self, build_preflight_headers, check_cors_response, needs_preflight, validate_preflight,
     CredentialsMode, PreflightCache,
 };
-use we_net::http::{ContentType, Headers, Method};
+use we_net::http::{ContentType, Headers, HttpResponse, Method};
+use we_net::referrer::{self, ReferrerPolicy};
 use we_url::data_url::{is_data_url, parse_data_url};
 use we_url::{Origin, Url};
 
@@ -114,6 +115,10 @@ pub enum Resource {
 pub struct ResourceLoader {
     client: HttpClient,
     preflight_cache: PreflightCache,
+    /// The document URL used as the referrer source for subresource requests.
+    document_url: Option<Url>,
+    /// The active referrer policy for this document.
+    referrer_policy: ReferrerPolicy,
 }
 
 impl ResourceLoader {
@@ -122,6 +127,57 @@ impl ResourceLoader {
         Self {
             client: HttpClient::new(),
             preflight_cache: PreflightCache::new(),
+            document_url: None,
+            referrer_policy: ReferrerPolicy::default(),
+        }
+    }
+
+    /// Set the document URL (used as the referrer source).
+    pub fn set_document_url(&mut self, url: &Url) {
+        self.document_url = Some(url.clone());
+    }
+
+    /// Set the referrer policy for this document.
+    pub fn set_referrer_policy(&mut self, policy: ReferrerPolicy) {
+        self.referrer_policy = policy;
+    }
+
+    /// Get the current referrer policy.
+    pub fn referrer_policy(&self) -> ReferrerPolicy {
+        self.referrer_policy
+    }
+
+    /// Compute the Referer header value for a request to `target_url`,
+    /// using an optional element-level policy override.
+    fn compute_referer(
+        &self,
+        target_url: &Url,
+        element_policy: Option<ReferrerPolicy>,
+    ) -> Option<String> {
+        let doc_url = self.document_url.as_ref()?;
+        let policy = element_policy.unwrap_or(self.referrer_policy);
+        referrer::compute_referrer(doc_url, target_url, policy)
+    }
+
+    /// Add the Referer header to a headers collection if appropriate.
+    fn add_referer_header(
+        &self,
+        headers: &mut Headers,
+        target_url: &Url,
+        element_policy: Option<ReferrerPolicy>,
+    ) {
+        if let Some(referer) = self.compute_referer(target_url, element_policy) {
+            headers.set("Referer", &referer);
+        }
+    }
+
+    /// Check the response for a `Referrer-Policy` header and update
+    /// the document-level policy if one is found.
+    fn update_policy_from_response(&mut self, response: &HttpResponse) {
+        if let Some(header_val) = response.headers.get("Referrer-Policy") {
+            if let Some(policy) = ReferrerPolicy::parse_header(header_val) {
+                self.referrer_policy = policy;
+            }
         }
     }
 
@@ -143,7 +199,10 @@ impl ResourceLoader {
             return fetch_about_url(url);
         }
 
-        let response = self.client.get(url)?;
+        let mut headers = Headers::new();
+        self.add_referer_header(&mut headers, url, None);
+        let response = self.client.request(Method::Get, url, &headers, None)?;
+        self.update_policy_from_response(&response);
 
         // Check for HTTP error status codes
         if response.status_code >= 400 {
@@ -222,13 +281,33 @@ impl ResourceLoader {
         document_origin: &Origin,
         request_type: ResourceRequestType,
     ) -> Result<Resource, LoadError> {
-        self.fetch_subresource_with_cors(
+        self.fetch_subresource_with_options(
+            url,
+            document_origin,
+            request_type,
+            Method::Get,
+            &Headers::new(),
+            CredentialsMode::SameOrigin,
+            None,
+        )
+    }
+
+    /// Fetch a subresource with an element-level referrer policy override.
+    pub fn fetch_subresource_with_referrer_policy(
+        &mut self,
+        url: &Url,
+        document_origin: &Origin,
+        request_type: ResourceRequestType,
+        element_policy: Option<ReferrerPolicy>,
+    ) -> Result<Resource, LoadError> {
+        self.fetch_subresource_with_options(
             url,
             document_origin,
             request_type,
             Method::Get,
             &Headers::new(),
             CredentialsMode::SameOrigin,
+            element_policy,
         )
     }
 
@@ -241,6 +320,29 @@ impl ResourceLoader {
         method: Method,
         extra_headers: &Headers,
         credentials_mode: CredentialsMode,
+    ) -> Result<Resource, LoadError> {
+        self.fetch_subresource_with_options(
+            url,
+            document_origin,
+            request_type,
+            method,
+            extra_headers,
+            credentials_mode,
+            None,
+        )
+    }
+
+    /// Fetch a subresource with full CORS control and optional referrer policy override.
+    #[allow(clippy::too_many_arguments)]
+    fn fetch_subresource_with_options(
+        &mut self,
+        url: &Url,
+        document_origin: &Origin,
+        request_type: ResourceRequestType,
+        method: Method,
+        extra_headers: &Headers,
+        credentials_mode: CredentialsMode,
+        element_policy: Option<ReferrerPolicy>,
     ) -> Result<Resource, LoadError> {
         // data: and about: URLs are always allowed (local, no network).
         if url.scheme() == "data" || url.scheme() == "about" {
@@ -257,7 +359,13 @@ impl ResourceLoader {
         let resource_origin = url.origin();
         if document_origin.same_origin(&resource_origin) {
             // Same-origin: no CORS needed, use provided method and headers.
-            let response = self.client.request(method, url, extra_headers, None)?;
+            let mut merged = Headers::new();
+            for (name, value) in extra_headers.iter() {
+                merged.add(name, value);
+            }
+            self.add_referer_header(&mut merged, url, element_policy);
+            let response = self.client.request(method, url, &merged, None)?;
+            self.update_policy_from_response(&response);
             if response.status_code >= 400 {
                 return Err(LoadError::HttpStatus {
                     status: response.status_code,
@@ -270,12 +378,13 @@ impl ResourceLoader {
         // Cross-origin: CORS flow.
         let url_str = url.serialize();
 
-        // Add Origin header to the request.
+        // Add Origin and Referer headers to the request.
         let mut request_headers = Headers::new();
         for (name, value) in extra_headers.iter() {
             request_headers.add(name, value);
         }
         request_headers.set("Origin", &document_origin.serialize());
+        self.add_referer_header(&mut request_headers, url, element_policy);
 
         // Check if a preflight is needed.
         if needs_preflight(method, extra_headers) {
@@ -306,6 +415,7 @@ impl ResourceLoader {
 
         // Perform the actual request.
         let response = self.client.request(method, url, &request_headers, None)?;
+        self.update_policy_from_response(&response);
 
         if response.status_code >= 400 {
             return Err(LoadError::HttpStatus {
diff --git a/crates/browser/src/main.rs b/crates/browser/src/main.rs
index d2c5b53..b8b70e5 100644
--- a/crates/browser/src/main.rs
+++ b/crates/browser/src/main.rs
@@ -11,6 +11,7 @@ use we_dom::{Document, NodeData, NodeId};
 use we_html::parse_html;
 use we_image::pixel::Image;
 use we_layout::layout;
+use we_net::referrer::ReferrerPolicy;
 use we_platform::appkit;
 use we_platform::cg::BitmapContext;
 use we_platform::metal::ClearColor;
@@ -341,6 +342,8 @@ fn handle_scroll(_dx: f64, dy: f64, _mouse_x: f64, _mouse_y: f64) {
 struct LoadedHtml {
     text: String,
     base_url: Url,
+    /// Referrer policy from the HTTP Referrer-Policy response header, if any.
+    http_referrer_policy: Option<ReferrerPolicy>,
 }
 
 /// Load content from a command-line argument.
@@ -358,7 +361,17 @@ fn load_from_arg(arg: &str) -> LoadedHtml {
         let mut loader = ResourceLoader::new();
         match loader.fetch_url(arg, None) {
             Ok(Resource::Html { text, base_url, .. }) => {
-                return LoadedHtml { text, base_url };
+                // Capture referrer policy from the HTTP response (if loader updated it).
+                let http_policy = if loader.referrer_policy() != ReferrerPolicy::default() {
+                    Some(loader.referrer_policy())
+                } else {
+                    None
+                };
+                return LoadedHtml {
+                    text,
+                    base_url,
+                    http_referrer_policy: http_policy,
+                };
             }
             Ok(_) => {
                 return error_page(&format!("URL did not return HTML: {arg}"));
@@ -382,6 +395,7 @@ fn load_from_arg(arg: &str) -> LoadedHtml {
             LoadedHtml {
                 text: content,
                 base_url,
+                http_referrer_policy: None,
             }
         }
         Err(e) => error_page(&format!("Error reading {arg}: {e}")),
@@ -409,16 +423,47 @@ fn error_page(message: &str) -> LoadedHtml {
     LoadedHtml {
         text: html,
         base_url,
+        http_referrer_policy: None,
     }
 }
 
+/// Extract the referrer policy from `<meta name="referrer" content="...">` in the DOM.
+fn extract_meta_referrer_policy(doc: &Document) -> Option<ReferrerPolicy> {
+    let mut result = None;
+    for i in 0..doc.len() {
+        let node_id = NodeId::from_index(i);
+        if doc.tag_name(node_id) == Some("meta") {
+            if let Some(name_attr) = doc.get_attribute(node_id, "name") {
+                if name_attr.eq_ignore_ascii_case("referrer") {
+                    if let Some(content) = doc.get_attribute(node_id, "content") {
+                        if let Some(policy) = ReferrerPolicy::parse(content) {
+                            // Last valid meta referrer wins.
+                            result = Some(policy);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    result
+}
+
 /// Load a page: fetch HTML, parse DOM, execute scripts, collect CSS, load web fonts, and images.
 fn load_page(loaded: LoadedHtml) -> PageState {
     let doc = parse_html(&loaded.text);
 
+    // Determine the referrer policy. Priority: meta tag > HTTP header > default.
+    let meta_policy = extract_meta_referrer_policy(&doc);
+
     // Execute <script> elements. Scripts may modify the DOM, so this must
     // run before collecting CSS and images (which depend on DOM structure).
     let mut loader = ResourceLoader::new();
+    loader.set_document_url(&loaded.base_url);
+    if let Some(policy) = meta_policy {
+        loader.set_referrer_policy(policy);
+    } else if let Some(policy) = loaded.http_referrer_policy {
+        loader.set_referrer_policy(policy);
+    }
     let doc = execute_page_scripts(doc, &mut loader, &loaded.base_url);
 
     // Fetch external stylesheets and merge with inline <style> elements.
@@ -461,6 +506,7 @@ fn main() {
         None => LoadedHtml {
             text: ABOUT_BLANK_HTML.to_string(),
             base_url: Url::parse("about:blank").expect("about:blank is always valid"),
+            http_referrer_policy: None,
         },
     };
 
diff --git a/crates/browser/src/script_loader.rs b/crates/browser/src/script_loader.rs
index 303b5f6..dc18e0b 100644
--- a/crates/browser/src/script_loader.rs
+++ b/crates/browser/src/script_loader.rs
@@ -8,6 +8,7 @@ use we_dom::{Document, NodeId};
 use we_js::compiler;
 use we_js::parser::Parser;
 use we_js::vm::Vm;
+use we_net::referrer::ReferrerPolicy;
 use we_url::{Origin, Url};
 
 /// Information about a `<script>` element extracted from the DOM.
@@ -22,6 +23,8 @@ struct ScriptInfo {
     async_attr: bool,
     /// The `type` attribute value, if any.
     type_attr: Option<String>,
+    /// Element-level referrer policy override (`referrerpolicy` attribute).
+    referrer_policy: Option<ReferrerPolicy>,
 }
 
 /// Returns true if a script's `type` attribute indicates it should execute.
@@ -70,6 +73,9 @@ fn extract_script_info(doc: &Document, node: NodeId) -> ScriptInfo {
     let defer = doc.get_attribute(node, "defer").is_some();
     let async_attr = doc.get_attribute(node, "async").is_some();
     let type_attr = doc.get_attribute(node, "type").map(|s| s.to_string());
+    let referrer_policy = doc
+        .get_attribute(node, "referrerpolicy")
+        .and_then(ReferrerPolicy::parse);
 
     let text = if src.is_none() {
         let content = collect_text_content(doc, node);
@@ -88,6 +94,7 @@ fn extract_script_info(doc: &Document, node: NodeId) -> ScriptInfo {
         defer,
         async_attr,
         type_attr,
+        referrer_policy,
     }
 }
 
@@ -97,12 +104,21 @@ fn fetch_script_text(
     src: &str,
     base_url: &Url,
     document_origin: &Origin,
+    element_policy: Option<ReferrerPolicy>,
 ) -> Option<String> {
-    match loader.fetch_url_subresource(
-        src,
-        Some(base_url),
+    let url = match we_url::Url::parse_with_base(src, base_url).or_else(|_| we_url::Url::parse(src))
+    {
+        Ok(u) => u,
+        Err(_) => {
+            eprintln!("[script] invalid URL: {src}");
+            return None;
+        }
+    };
+    match loader.fetch_subresource_with_referrer_policy(
+        &url,
         document_origin,
         ResourceRequestType::Script,
+        element_policy,
     ) {
         Ok(Resource::Script { text, .. }) => Some(text),
         Ok(Resource::Other { data, .. }) => {
@@ -207,7 +223,7 @@ pub fn execute_page_scripts_with_origin(
         // Resolve the script source text.
         let (source, label) = if let Some(ref src) = info.src {
             // External script: fetch it.
-            match fetch_script_text(loader, src, base_url, document_origin) {
+            match fetch_script_text(loader, src, base_url, document_origin, info.referrer_policy) {
                 Some(text) => (text, src.clone()),
                 None => continue,
             }
diff --git a/crates/net/src/lib.rs b/crates/net/src/lib.rs
index 776cc01..1240ef3 100644
--- a/crates/net/src/lib.rs
+++ b/crates/net/src/lib.rs
@@ -1,9 +1,10 @@
-//! TCP, DNS, pure-Rust TLS 1.3, HTTP/1.1, HTTP/2, CORS.
+//! TCP, DNS, pure-Rust TLS 1.3, HTTP/1.1, HTTP/2, CORS, Referrer Policy.
 
 pub mod client;
 pub mod cookie;
 pub mod cors;
 pub mod dns;
 pub mod http;
+pub mod referrer;
 pub mod tcp;
 pub mod tls;
diff --git a/crates/net/src/referrer.rs b/crates/net/src/referrer.rs
new file mode 100644
index 0000000..914e68e
--- /dev/null
+++ b/crates/net/src/referrer.rs
@@ -0,0 +1,691 @@
+//! Referrer Policy implementation (W3C Referrer Policy).
+//!
+//! Computes the value of the `Referer` header sent with HTTP requests based
+//! on the active referrer policy, the document URL, and the request URL.
+//!
+//! Supported policies:
+//! - `no-referrer`
+//! - `no-referrer-when-downgrade` (the default)
+//! - `origin`
+//! - `origin-when-cross-origin`
+//! - `same-origin`
+//! - `strict-origin`
+//! - `strict-origin-when-cross-origin`
+//! - `unsafe-url`
+
+use we_url::{Origin, Url};
+
+/// The eight referrer policies defined by the W3C Referrer Policy spec.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum ReferrerPolicy {
+    /// Never send referrer information.
+    NoReferrer,
+    /// Send full URL for same-protocol requests; no referrer on downgrade (HTTPS→HTTP).
+    /// This is the historical default.
+    NoReferrerWhenDowngrade,
+    /// Always send origin only (scheme + host + port).
+    Origin,
+    /// Send full URL for same-origin; origin only for cross-origin.
+    OriginWhenCrossOrigin,
+    /// Send full URL for same-origin requests only.
+    SameOrigin,
+    /// Send origin for same-protocol; no referrer on downgrade.
+    StrictOrigin,
+    /// Send full URL for same-origin; origin for cross-origin same-protocol;
+    /// no referrer on downgrade. This is the modern default.
+    #[default]
+    StrictOriginWhenCrossOrigin,
+    /// Always send the full URL (stripped of fragment and userinfo).
+    UnsafeUrl,
+}
+
+impl ReferrerPolicy {
+    /// Parse a referrer policy from a string (case-insensitive).
+    ///
+    /// Returns `None` for unrecognized values (per spec, unknown tokens are
+    /// ignored and the existing policy remains in effect).
+    pub fn parse(value: &str) -> Option<Self> {
+        match value.trim().to_ascii_lowercase().as_str() {
+            "no-referrer" => Some(Self::NoReferrer),
+            "no-referrer-when-downgrade" => Some(Self::NoReferrerWhenDowngrade),
+            "origin" => Some(Self::Origin),
+            "origin-when-cross-origin" => Some(Self::OriginWhenCrossOrigin),
+            "same-origin" => Some(Self::SameOrigin),
+            "strict-origin" => Some(Self::StrictOrigin),
+            "strict-origin-when-cross-origin" => Some(Self::StrictOriginWhenCrossOrigin),
+            "unsafe-url" => Some(Self::UnsafeUrl),
+            "" => Some(Self::default()),
+            _ => None,
+        }
+    }
+
+    /// Parse a `Referrer-Policy` HTTP response header.
+    ///
+    /// Per spec, the header may contain a comma-separated list of policy tokens.
+    /// The *last* valid token wins (allows graceful degradation for older clients).
+    pub fn parse_header(header_value: &str) -> Option<Self> {
+        let mut result = None;
+        for token in header_value.split(',') {
+            if let Some(policy) = Self::parse(token) {
+                result = Some(policy);
+            }
+        }
+        result
+    }
+
+    /// Return the policy name as it appears in headers and attributes.
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::NoReferrer => "no-referrer",
+            Self::NoReferrerWhenDowngrade => "no-referrer-when-downgrade",
+            Self::Origin => "origin",
+            Self::OriginWhenCrossOrigin => "origin-when-cross-origin",
+            Self::SameOrigin => "same-origin",
+            Self::StrictOrigin => "strict-origin",
+            Self::StrictOriginWhenCrossOrigin => "strict-origin-when-cross-origin",
+            Self::UnsafeUrl => "unsafe-url",
+        }
+    }
+}
+
+/// Compute the `Referer` header value for a request.
+///
+/// Given the document (referrer) URL, the request (destination) URL, and
+/// the active referrer policy, returns the appropriate `Referer` header
+/// value, or `None` if the referrer should be suppressed entirely.
+pub fn compute_referrer(
+    referrer_url: &Url,
+    request_url: &Url,
+    policy: ReferrerPolicy,
+) -> Option<String> {
+    // Per spec: referrer URLs with non-HTTP(S) schemes don't produce a referrer.
+    let referrer_scheme = referrer_url.scheme();
+    if referrer_scheme != "http" && referrer_scheme != "https" {
+        return None;
+    }
+
+    match policy {
+        ReferrerPolicy::NoReferrer => None,
+
+        ReferrerPolicy::NoReferrerWhenDowngrade => {
+            if is_downgrade(referrer_url, request_url) {
+                None
+            } else {
+                Some(strip_referrer_url(referrer_url))
+            }
+        }
+
+        ReferrerPolicy::Origin => Some(origin_only(referrer_url)),
+
+        ReferrerPolicy::OriginWhenCrossOrigin => {
+            if is_same_origin(referrer_url, request_url) {
+                Some(strip_referrer_url(referrer_url))
+            } else {
+                Some(origin_only(referrer_url))
+            }
+        }
+
+        ReferrerPolicy::SameOrigin => {
+            if is_same_origin(referrer_url, request_url) {
+                Some(strip_referrer_url(referrer_url))
+            } else {
+                None
+            }
+        }
+
+        ReferrerPolicy::StrictOrigin => {
+            if is_downgrade(referrer_url, request_url) {
+                None
+            } else {
+                Some(origin_only(referrer_url))
+            }
+        }
+
+        ReferrerPolicy::StrictOriginWhenCrossOrigin => {
+            if is_same_origin(referrer_url, request_url) {
+                Some(strip_referrer_url(referrer_url))
+            } else if is_downgrade(referrer_url, request_url) {
+                None
+            } else {
+                Some(origin_only(referrer_url))
+            }
+        }
+
+        ReferrerPolicy::UnsafeUrl => Some(strip_referrer_url(referrer_url)),
+    }
+}
+
+/// Check if the request is a "downgrade" (HTTPS referrer → HTTP destination).
+fn is_downgrade(referrer: &Url, request: &Url) -> bool {
+    referrer.scheme() == "https" && request.scheme() == "http"
+}
+
+/// Check if two URLs are same-origin.
+fn is_same_origin(a: &Url, b: &Url) -> bool {
+    a.origin().same_origin(&b.origin())
+}
+
+/// Strip a URL for use as a referrer: remove fragment and userinfo,
+/// keep scheme, host, port, path, and query.
+fn strip_referrer_url(url: &Url) -> String {
+    let mut result = String::new();
+    result.push_str(url.scheme());
+    result.push_str("://");
+    if let Some(host) = url.host_str() {
+        result.push_str(&host);
+    }
+    if let Some(port) = url.port() {
+        result.push(':');
+        result.push_str(&port.to_string());
+    }
+    result.push_str(&url.path());
+    if let Some(query) = url.query() {
+        result.push('?');
+        result.push_str(query);
+    }
+    result
+}
+
+/// Return origin-only form of a URL: scheme + "://" + host [+ ":" + port] + "/".
+fn origin_only(url: &Url) -> String {
+    match url.origin() {
+        Origin::Tuple(scheme, host, port) => {
+            let mut s = String::new();
+            s.push_str(&scheme);
+            s.push_str("://");
+            s.push_str(&host.serialize());
+            if let Some(p) = port {
+                s.push(':');
+                s.push_str(&p.to_string());
+            }
+            s.push('/');
+            s
+        }
+        Origin::Opaque => "null".to_string(),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // -- Policy parsing --
+
+    #[test]
+    fn parse_no_referrer() {
+        assert_eq!(
+            ReferrerPolicy::parse("no-referrer"),
+            Some(ReferrerPolicy::NoReferrer)
+        );
+    }
+
+    #[test]
+    fn parse_no_referrer_when_downgrade() {
+        assert_eq!(
+            ReferrerPolicy::parse("no-referrer-when-downgrade"),
+            Some(ReferrerPolicy::NoReferrerWhenDowngrade)
+        );
+    }
+
+    #[test]
+    fn parse_origin() {
+        assert_eq!(
+            ReferrerPolicy::parse("origin"),
+            Some(ReferrerPolicy::Origin)
+        );
+    }
+
+    #[test]
+    fn parse_origin_when_cross_origin() {
+        assert_eq!(
+            ReferrerPolicy::parse("origin-when-cross-origin"),
+            Some(ReferrerPolicy::OriginWhenCrossOrigin)
+        );
+    }
+
+    #[test]
+    fn parse_same_origin() {
+        assert_eq!(
+            ReferrerPolicy::parse("same-origin"),
+            Some(ReferrerPolicy::SameOrigin)
+        );
+    }
+
+    #[test]
+    fn parse_strict_origin() {
+        assert_eq!(
+            ReferrerPolicy::parse("strict-origin"),
+            Some(ReferrerPolicy::StrictOrigin)
+        );
+    }
+
+    #[test]
+    fn parse_strict_origin_when_cross_origin() {
+        assert_eq!(
+            ReferrerPolicy::parse("strict-origin-when-cross-origin"),
+            Some(ReferrerPolicy::StrictOriginWhenCrossOrigin)
+        );
+    }
+
+    #[test]
+    fn parse_unsafe_url() {
+        assert_eq!(
+            ReferrerPolicy::parse("unsafe-url"),
+            Some(ReferrerPolicy::UnsafeUrl)
+        );
+    }
+
+    #[test]
+    fn parse_unknown_returns_none() {
+        assert_eq!(ReferrerPolicy::parse("bogus"), None);
+    }
+
+    #[test]
+    fn parse_case_insensitive() {
+        assert_eq!(
+            ReferrerPolicy::parse("No-Referrer"),
+            Some(ReferrerPolicy::NoReferrer)
+        );
+        assert_eq!(
+            ReferrerPolicy::parse("STRICT-ORIGIN"),
+            Some(ReferrerPolicy::StrictOrigin)
+        );
+    }
+
+    #[test]
+    fn parse_with_whitespace() {
+        assert_eq!(
+            ReferrerPolicy::parse("  no-referrer  "),
+            Some(ReferrerPolicy::NoReferrer)
+        );
+    }
+
+    #[test]
+    fn parse_empty_returns_default() {
+        assert_eq!(
+            ReferrerPolicy::parse(""),
+            Some(ReferrerPolicy::StrictOriginWhenCrossOrigin)
+        );
+    }
+
+    // -- Header parsing (comma-separated, last valid wins) --
+
+    #[test]
+    fn parse_header_single() {
+        assert_eq!(
+            ReferrerPolicy::parse_header("no-referrer"),
+            Some(ReferrerPolicy::NoReferrer)
+        );
+    }
+
+    #[test]
+    fn parse_header_multiple_last_wins() {
+        assert_eq!(
+            ReferrerPolicy::parse_header("no-referrer, origin"),
+            Some(ReferrerPolicy::Origin)
+        );
+    }
+
+    #[test]
+    fn parse_header_unknown_tokens_ignored() {
+        assert_eq!(
+            ReferrerPolicy::parse_header("bogus, no-referrer"),
+            Some(ReferrerPolicy::NoReferrer)
+        );
+    }
+
+    #[test]
+    fn parse_header_all_unknown() {
+        assert_eq!(ReferrerPolicy::parse_header("bogus, also-bogus"), None);
+    }
+
+    #[test]
+    fn parse_header_graceful_degradation() {
+        // Newer policy listed first, older fallback listed last.
+        // Older client ignores unknown, picks fallback.
+        assert_eq!(
+            ReferrerPolicy::parse_header(
+                "strict-origin-when-cross-origin, no-referrer-when-downgrade"
+            ),
+            Some(ReferrerPolicy::NoReferrerWhenDowngrade)
+        );
+    }
+
+    // -- as_str round-trip --
+
+    #[test]
+    fn as_str_round_trip() {
+        let policies = [
+            ReferrerPolicy::NoReferrer,
+            ReferrerPolicy::NoReferrerWhenDowngrade,
+            ReferrerPolicy::Origin,
+            ReferrerPolicy::OriginWhenCrossOrigin,
+            ReferrerPolicy::SameOrigin,
+            ReferrerPolicy::StrictOrigin,
+            ReferrerPolicy::StrictOriginWhenCrossOrigin,
+            ReferrerPolicy::UnsafeUrl,
+        ];
+        for policy in &policies {
+            assert_eq!(ReferrerPolicy::parse(policy.as_str()), Some(*policy));
+        }
+    }
+
+    // -- Default --
+
+    #[test]
+    fn default_policy() {
+        assert_eq!(
+            ReferrerPolicy::default(),
+            ReferrerPolicy::StrictOriginWhenCrossOrigin
+        );
+    }
+
+    // -- Referrer stripping helpers --
+
+    #[test]
+    fn strip_removes_fragment() {
+        let url = Url::parse("https://example.com/page#section").unwrap();
+        let stripped = strip_referrer_url(&url);
+        assert_eq!(stripped, "https://example.com/page");
+        assert!(!stripped.contains('#'));
+    }
+
+    #[test]
+    fn strip_removes_userinfo() {
+        let url = Url::parse("https://user:pass@example.com/page").unwrap();
+        let stripped = strip_referrer_url(&url);
+        assert_eq!(stripped, "https://example.com/page");
+        assert!(!stripped.contains("user"));
+        assert!(!stripped.contains("pass"));
+    }
+
+    #[test]
+    fn strip_preserves_query() {
+        let url = Url::parse("https://example.com/page?key=value").unwrap();
+        let stripped = strip_referrer_url(&url);
+        assert_eq!(stripped, "https://example.com/page?key=value");
+    }
+
+    #[test]
+    fn strip_preserves_path() {
+        let url = Url::parse("https://example.com/a/b/c").unwrap();
+        let stripped = strip_referrer_url(&url);
+        assert_eq!(stripped, "https://example.com/a/b/c");
+    }
+
+    #[test]
+    fn strip_preserves_port() {
+        let url = Url::parse("https://example.com:8443/page").unwrap();
+        let stripped = strip_referrer_url(&url);
+        assert_eq!(stripped, "https://example.com:8443/page");
+    }
+
+    #[test]
+    fn origin_only_format() {
+        let url = Url::parse("https://example.com/page?q=1#frag").unwrap();
+        let origin = origin_only(&url);
+        assert_eq!(origin, "https://example.com/");
+    }
+
+    #[test]
+    fn origin_only_with_port() {
+        let url = Url::parse("https://example.com:8443/page").unwrap();
+        let origin = origin_only(&url);
+        assert_eq!(origin, "https://example.com:8443/");
+    }
+
+    // -- compute_referrer: NoReferrer --
+
+    #[test]
+    fn no_referrer_always_none() {
+        let doc = Url::parse("https://example.com/page").unwrap();
+        let req = Url::parse("https://example.com/other").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::NoReferrer),
+            None
+        );
+    }
+
+    // -- compute_referrer: NoReferrerWhenDowngrade --
+
+    #[test]
+    fn no_referrer_when_downgrade_same_protocol() {
+        let doc = Url::parse("https://example.com/page").unwrap();
+        let req = Url::parse("https://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::NoReferrerWhenDowngrade),
+            Some("https://example.com/page".to_string())
+        );
+    }
+
+    #[test]
+    fn no_referrer_when_downgrade_https_to_http() {
+        let doc = Url::parse("https://example.com/page").unwrap();
+        let req = Url::parse("http://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::NoReferrerWhenDowngrade),
+            None
+        );
+    }
+
+    #[test]
+    fn no_referrer_when_downgrade_http_to_http() {
+        let doc = Url::parse("http://example.com/page").unwrap();
+        let req = Url::parse("http://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::NoReferrerWhenDowngrade),
+            Some("http://example.com/page".to_string())
+        );
+    }
+
+    #[test]
+    fn no_referrer_when_downgrade_http_to_https() {
+        let doc = Url::parse("http://example.com/page").unwrap();
+        let req = Url::parse("https://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::NoReferrerWhenDowngrade),
+            Some("http://example.com/page".to_string())
+        );
+    }
+
+    // -- compute_referrer: Origin --
+
+    #[test]
+    fn origin_always_sends_origin() {
+        let doc = Url::parse("https://example.com/page?secret=1").unwrap();
+        let req = Url::parse("https://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::Origin),
+            Some("https://example.com/".to_string())
+        );
+    }
+
+    #[test]
+    fn origin_on_downgrade() {
+        let doc = Url::parse("https://example.com/page").unwrap();
+        let req = Url::parse("http://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::Origin),
+            Some("https://example.com/".to_string())
+        );
+    }
+
+    // -- compute_referrer: OriginWhenCrossOrigin --
+
+    #[test]
+    fn origin_when_cross_origin_same() {
+        let doc = Url::parse("https://example.com/page?q=1").unwrap();
+        let req = Url::parse("https://example.com/other").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::OriginWhenCrossOrigin),
+            Some("https://example.com/page?q=1".to_string())
+        );
+    }
+
+    #[test]
+    fn origin_when_cross_origin_different() {
+        let doc = Url::parse("https://example.com/page?q=1").unwrap();
+        let req = Url::parse("https://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::OriginWhenCrossOrigin),
+            Some("https://example.com/".to_string())
+        );
+    }
+
+    // -- compute_referrer: SameOrigin --
+
+    #[test]
+    fn same_origin_sends_for_same() {
+        let doc = Url::parse("https://example.com/page").unwrap();
+        let req = Url::parse("https://example.com/other").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::SameOrigin),
+            Some("https://example.com/page".to_string())
+        );
+    }
+
+    #[test]
+    fn same_origin_suppresses_for_cross() {
+        let doc = Url::parse("https://example.com/page").unwrap();
+        let req = Url::parse("https://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::SameOrigin),
+            None
+        );
+    }
+
+    // -- compute_referrer: StrictOrigin --
+
+    #[test]
+    fn strict_origin_same_protocol() {
+        let doc = Url::parse("https://example.com/page").unwrap();
+        let req = Url::parse("https://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::StrictOrigin),
+            Some("https://example.com/".to_string())
+        );
+    }
+
+    #[test]
+    fn strict_origin_downgrade() {
+        let doc = Url::parse("https://example.com/page").unwrap();
+        let req = Url::parse("http://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::StrictOrigin),
+            None
+        );
+    }
+
+    #[test]
+    fn strict_origin_http_to_http() {
+        let doc = Url::parse("http://example.com/page").unwrap();
+        let req = Url::parse("http://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::StrictOrigin),
+            Some("http://example.com/".to_string())
+        );
+    }
+
+    // -- compute_referrer: StrictOriginWhenCrossOrigin --
+
+    #[test]
+    fn strict_origin_cross_origin_same_origin() {
+        let doc = Url::parse("https://example.com/page?secret=1").unwrap();
+        let req = Url::parse("https://example.com/other").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::StrictOriginWhenCrossOrigin),
+            Some("https://example.com/page?secret=1".to_string())
+        );
+    }
+
+    #[test]
+    fn strict_origin_cross_origin_cross_origin_no_downgrade() {
+        let doc = Url::parse("https://example.com/page?secret=1").unwrap();
+        let req = Url::parse("https://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::StrictOriginWhenCrossOrigin),
+            Some("https://example.com/".to_string())
+        );
+    }
+
+    #[test]
+    fn strict_origin_cross_origin_downgrade() {
+        let doc = Url::parse("https://example.com/page").unwrap();
+        let req = Url::parse("http://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::StrictOriginWhenCrossOrigin),
+            None
+        );
+    }
+
+    // -- compute_referrer: UnsafeUrl --
+
+    #[test]
+    fn unsafe_url_always_sends_full() {
+        let doc = Url::parse("https://example.com/page?q=1").unwrap();
+        let req = Url::parse("http://other.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::UnsafeUrl),
+            Some("https://example.com/page?q=1".to_string())
+        );
+    }
+
+    #[test]
+    fn unsafe_url_strips_fragment() {
+        let doc = Url::parse("https://example.com/page#frag").unwrap();
+        let req = Url::parse("https://other.com/resource").unwrap();
+        let result = compute_referrer(&doc, &req, ReferrerPolicy::UnsafeUrl).unwrap();
+        assert!(!result.contains('#'));
+        assert_eq!(result, "https://example.com/page");
+    }
+
+    // -- Non-HTTP referrer URLs --
+
+    #[test]
+    fn non_http_referrer_suppressed() {
+        let doc = Url::parse("file:///home/user/page.html").unwrap();
+        let req = Url::parse("https://example.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::UnsafeUrl),
+            None
+        );
+    }
+
+    #[test]
+    fn data_url_referrer_suppressed() {
+        let doc = Url::parse("data:text/html,Hello").unwrap();
+        let req = Url::parse("https://example.com/resource").unwrap();
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::UnsafeUrl),
+            None
+        );
+    }
+
+    // -- Edge cases --
+
+    #[test]
+    fn same_origin_different_port() {
+        let doc = Url::parse("https://example.com:8443/page").unwrap();
+        let req = Url::parse("https://example.com/resource").unwrap();
+        // Different ports → different origin
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::SameOrigin),
+            None
+        );
+    }
+
+    #[test]
+    fn same_origin_different_scheme() {
+        let doc = Url::parse("http://example.com/page").unwrap();
+        let req = Url::parse("https://example.com/resource").unwrap();
+        // Different schemes → different origin
+        assert_eq!(
+            compute_referrer(&doc, &req, ReferrerPolicy::SameOrigin),
+            None
+        );
+    }
+}
-- 
2.51.2