Skip to main content

qualia_client_core/
cookie_graph.rs

1//! Cookie / personal-data transparency graph (v0).
2//!
3//! Honest scope:
4//! - Model: site origin → cookie name → attributes → purpose hypothesis (heuristic).
5//! - Persist under `{storage}/webizen/cookie_graph.json`.
6//! - Observe: v0 accepts agent-fetched `Set-Cookie` headers and/or explicit observations
7//!   from the host. Full WebView2 cookie-jar parity is **not** claimed.
8//! - No MITM proxy.
9
10use std::fs;
11use std::path::{Path, PathBuf};
12
13use serde::{Deserialize, Serialize};
14
15pub const COOKIE_GRAPH_FILE: &str = "webizen/cookie_graph.json";
16
17#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
18#[serde(rename_all = "snake_case")]
19pub enum CookiePurposeHypothesis {
20    Session,
21    Analytics,
22    Tracker,
23    Preference,
24    Auth,
25    Unknown,
26}
27
28#[derive(Debug, Clone, Serialize, Deserialize)]
29pub struct CookieNode {
30    pub origin: String,
31    pub name: String,
32    pub domain: String,
33    pub path: String,
34    pub secure: bool,
35    pub same_site: String,
36    pub expiry: Option<String>,
37    pub purpose: CookiePurposeHypothesis,
38    pub third_party: bool,
39    /// How we learned about this cookie (agent_set_cookie | host_observe | manual).
40    pub source: String,
41    pub observed_unix: u64,
42}
43
44#[derive(Debug, Clone, Serialize, Deserialize, Default)]
45pub struct CookieGraph {
46    pub version: u32,
47    pub nodes: Vec<CookieNode>,
48    /// Honest coverage label for UI.
49    pub coverage_note: String,
50}
51
52impl CookieGraph {
53    /// Creates a new instance.
54    pub fn new() -> Self {
55        Self {
56            version: 1,
57            nodes: Vec::new(),
58            coverage_note: "v1: WebView jar (cookies_for_url) + agent Set-Cookie observe — not complete Chromium parity.".into(),
59        }
60    }
61
62    /// Path.
63    pub fn path(storage_root: &Path) -> PathBuf {
64        storage_root.join(COOKIE_GRAPH_FILE)
65    }
66
67    /// Loads.
68    pub fn load(storage_root: &Path) -> Self {
69        let p = Self::path(storage_root);
70        match fs::read_to_string(&p) {
71            Ok(s) => serde_json::from_str(&s).unwrap_or_else(|_| Self::new()),
72            Err(_) => Self::new(),
73        }
74    }
75
76    /// Saves.
77    pub fn save(&self, storage_root: &Path) -> Result<(), String> {
78        let p = Self::path(storage_root);
79        if let Some(parent) = p.parent() {
80            fs::create_dir_all(parent).map_err(|e| e.to_string())?;
81        }
82        let bytes = serde_json::to_vec_pretty(self).map_err(|e| e.to_string())?;
83        let tmp = p.with_extension("json.tmp");
84        fs::write(&tmp, &bytes).map_err(|e| e.to_string())?;
85        fs::rename(&tmp, &p).map_err(|e| e.to_string())
86    }
87
88    /// Upserts a record.
89    pub fn upsert(&mut self, node: CookieNode) {
90        if let Some(existing) = self
91            .nodes
92            .iter_mut()
93            .find(|n| n.origin == node.origin && n.name == node.name && n.domain == node.domain)
94        {
95            *existing = node;
96        } else {
97            self.nodes.push(node);
98        }
99    }
100
101    /// Records for an origin.
102    pub fn for_origin(&self, origin: &str) -> Vec<&CookieNode> {
103        let o = origin.trim().trim_end_matches('/');
104        self.nodes
105            .iter()
106            .filter(|n| n.origin.trim_end_matches('/') == o)
107            .collect()
108    }
109
110    /// Third parties for a host.
111    pub fn third_parties_for_host(&self, host: &str) -> Vec<String> {
112        let host = host.trim().to_ascii_lowercase();
113        let mut out = Vec::new();
114        for n in &self.nodes {
115            if !n.third_party {
116                continue;
117            }
118            let page_host = host_of(&n.origin);
119            if page_host == host || n.origin.contains(&host) {
120                let d = n.domain.trim_start_matches('.').to_ascii_lowercase();
121                if !d.is_empty() && d != host && !out.contains(&d) {
122                    out.push(d);
123                }
124            }
125        }
126        out.sort();
127        out
128    }
129
130    /// Remove all graph nodes for an origin (exact match, trailing slash normalized).
131    pub fn clear_origin(&mut self, origin: &str) -> usize {
132        let o = origin.trim().trim_end_matches('/');
133        let before = self.nodes.len();
134        self.nodes.retain(|n| n.origin.trim_end_matches('/') != o);
135        before.saturating_sub(self.nodes.len())
136    }
137
138    /// Remove nodes whose page host matches (origin host or domain).
139    pub fn clear_host(&mut self, host: &str) -> usize {
140        let host = host.trim().to_ascii_lowercase();
141        let before = self.nodes.len();
142        self.nodes.retain(|n| {
143            let page = host_of(&n.origin);
144            let d = n.domain.trim_start_matches('.').to_ascii_lowercase();
145            page != host && d != host
146        });
147        before.saturating_sub(self.nodes.len())
148    }
149
150    /// Clear entire graph (principal request).
151    pub fn clear_all(&mut self) -> usize {
152        let n = self.nodes.len();
153        self.nodes.clear();
154        n
155    }
156}
157
158fn host_of(url_or_origin: &str) -> String {
159    let u = url_or_origin.trim();
160    let rest = u
161        .strip_prefix("https://")
162        .or_else(|| u.strip_prefix("http://"))
163        .unwrap_or(u);
164    rest.split(['/', '?', '#', ':'])
165        .next()
166        .unwrap_or("")
167        .to_ascii_lowercase()
168}
169
170/// Heuristic purpose from cookie name (not ground truth).
171pub fn hypothesize_purpose(name: &str) -> CookiePurposeHypothesis {
172    let n = name.to_ascii_lowercase();
173    if n.contains("session") || n == "sid" || n.starts_with("jsession") {
174        return CookiePurposeHypothesis::Session;
175    }
176    if n.contains("auth") || n.contains("token") || n.contains("login") || n == "jwt" {
177        return CookiePurposeHypothesis::Auth;
178    }
179    if n.contains("ga")
180        || n.contains("_utm")
181        || n.contains("analytics")
182        || n.starts_with("_gid")
183        || n.starts_with("_gat")
184    {
185        return CookiePurposeHypothesis::Analytics;
186    }
187    if n.contains("fbp")
188        || n.contains("fbc")
189        || n.contains("doubleclick")
190        || n.contains("track")
191        || n.contains("ads")
192    {
193        return CookiePurposeHypothesis::Tracker;
194    }
195    if n.contains("pref") || n.contains("theme") || n.contains("lang") || n.contains("consent") {
196        return CookiePurposeHypothesis::Preference;
197    }
198    CookiePurposeHypothesis::Unknown
199}
200
201/// Parse a single Set-Cookie header line into a CookieNode (best-effort).
202pub fn parse_set_cookie(
203    page_url: &str,
204    set_cookie: &str,
205    now: u64,
206    source: &str,
207) -> Option<CookieNode> {
208    let line = set_cookie.trim();
209    if line.is_empty() {
210        return None;
211    }
212    let mut parts = line.split(';');
213    let nv = parts.next()?.trim();
214    let (name, _value) = nv.split_once('=')?;
215    let name = name.trim();
216    if name.is_empty() {
217        return None;
218    }
219    let page_host = host_of(page_url);
220    let origin = if page_url.starts_with("http") {
221        // scheme://host
222        let scheme = if page_url.starts_with("https") {
223            "https"
224        } else {
225            "http"
226        };
227        format!("{scheme}://{page_host}")
228    } else {
229        page_url.to_string()
230    };
231
232    let mut domain = page_host.clone();
233    let mut path = "/".to_string();
234    let mut secure = false;
235    let mut same_site = "Lax".to_string();
236    let mut expiry = None;
237    for p in parts {
238        let p = p.trim();
239        let (k, v) = match p.split_once('=') {
240            Some((a, b)) => (a.trim(), b.trim()),
241            None => (p, ""),
242        };
243        let kl = k.to_ascii_lowercase();
244        match kl.as_str() {
245            "domain" => domain = v.trim_start_matches('.').to_ascii_lowercase(),
246            "path" => path = if v.is_empty() { "/".into() } else { v.into() },
247            "secure" => secure = true,
248            "samesite" => same_site = v.to_string(),
249            "expires" | "max-age" => expiry = Some(v.to_string()),
250            _ => {}
251        }
252    }
253    let third_party = {
254        let d = domain.trim_start_matches('.');
255        !d.is_empty() && d != page_host && !page_host.ends_with(&format!(".{d}"))
256    };
257    Some(CookieNode {
258        origin,
259        name: name.into(),
260        domain,
261        path,
262        secure,
263        same_site,
264        expiry,
265        purpose: hypothesize_purpose(name),
266        third_party,
267        source: source.into(),
268        observed_unix: now,
269    })
270}
271
272/// Observe many Set-Cookie lines for a page URL; persist graph.
273pub fn observe_set_cookies(
274    storage_root: &Path,
275    page_url: &str,
276    set_cookies: &[String],
277    now: u64,
278) -> Result<CookieGraph, String> {
279    let mut g = CookieGraph::load(storage_root);
280    for sc in set_cookies {
281        if let Some(node) = parse_set_cookie(page_url, sc, now, "agent_set_cookie") {
282            g.upsert(node);
283        }
284    }
285    g.save(storage_root)?;
286    Ok(g)
287}
288
289/// Summary for chrome UI.
290pub fn summary_for_url(storage_root: &Path, url: &str) -> serde_json::Value {
291    let g = CookieGraph::load(storage_root);
292    let host = host_of(url);
293    let origin = if url.starts_with("https") {
294        format!("https://{host}")
295    } else if url.starts_with("http") {
296        format!("http://{host}")
297    } else {
298        url.to_string()
299    };
300    let nodes = g.for_origin(&origin);
301    let third = g.third_parties_for_host(&host);
302    serde_json::json!({
303        "url": url,
304        "origin": origin,
305        "cookie_count": nodes.len(),
306        "cookies": nodes,
307        "third_parties": third,
308        "coverage_note": g.coverage_note,
309        "honesty": "view + graph coverage is best-effort; not complete Chromium jar parity",
310    })
311}
312
313/// Clear cookie graph for origin and optionally log intent for site-data clear.
314/// Does **not** by itself wipe the WebView jar — pair with platform clear.
315pub fn clear_graph_for_origin(
316    storage_root: &Path,
317    origin_or_url: &str,
318) -> Result<serde_json::Value, String> {
319    let host = host_of(origin_or_url);
320    let origin = if origin_or_url.starts_with("https") {
321        format!("https://{host}")
322    } else if origin_or_url.starts_with("http") {
323        format!("http://{host}")
324    } else if origin_or_url.contains("://") {
325        origin_or_url.trim().trim_end_matches('/').to_string()
326    } else {
327        format!("https://{host}")
328    };
329    let mut g = CookieGraph::load(storage_root);
330    let removed = g.clear_origin(&origin);
331    // Also drop host-matching third-party rows observed under this page host
332    let removed2 = g.clear_host(&host);
333    g.save(storage_root)?;
334    append_clear_audit(storage_root, &origin, removed + removed2, "origin")?;
335    Ok(serde_json::json!({
336        "origin": origin,
337        "host": host,
338        "removed_graph_nodes": removed + removed2,
339        "coverage_note": g.coverage_note,
340        "note": "Graph rows cleared. WebView jar clear is platform-side (see browser_clear_site_data).",
341    }))
342}
343
344/// Clears the whole graph.
345pub fn clear_graph_all(storage_root: &Path) -> Result<serde_json::Value, String> {
346    let mut g = CookieGraph::load(storage_root);
347    let n = g.clear_all();
348    g.save(storage_root)?;
349    append_clear_audit(storage_root, "*", n, "all")?;
350    Ok(serde_json::json!({
351        "removed_graph_nodes": n,
352        "note": "Entire cookie graph cleared. WebView jar may still hold cookies until platform clear.",
353    }))
354}
355
356fn append_clear_audit(
357    storage_root: &Path,
358    scope: &str,
359    removed: usize,
360    kind: &str,
361) -> Result<(), String> {
362    let path = storage_root.join("webizen/cookie_clear_audit.jsonl");
363    if let Some(p) = path.parent() {
364        fs::create_dir_all(p).map_err(|e| e.to_string())?;
365    }
366    let unix = std::time::SystemTime::now()
367        .duration_since(std::time::UNIX_EPOCH)
368        .map(|d| d.as_secs())
369        .unwrap_or(0);
370    let line = serde_json::json!({
371        "unix": unix,
372        "scope": scope,
373        "kind": kind,
374        "removed": removed,
375    });
376    use std::io::Write;
377    let mut f = fs::OpenOptions::new()
378        .create(true)
379        .append(true)
380        .open(&path)
381        .map_err(|e| e.to_string())?;
382    writeln!(
383        f,
384        "{}",
385        serde_json::to_string(&line).map_err(|e| e.to_string())?
386    )
387    .map_err(|e| e.to_string())?;
388    Ok(())
389}
390
391#[cfg(test)]
392mod tests {
393    use super::*;
394
395    #[test]
396    fn parse_and_persist() {
397        let dir = tempfile::tempdir().unwrap();
398        let sc = "SID=abc; Domain=example.org; Path=/; Secure; SameSite=None".to_string();
399        let g = observe_set_cookies(dir.path(), "https://example.org/page", &[sc], 1).unwrap();
400        assert_eq!(g.nodes.len(), 1);
401        assert_eq!(g.nodes[0].name, "SID");
402        assert_eq!(g.nodes[0].purpose, CookiePurposeHypothesis::Session);
403        let loaded = CookieGraph::load(dir.path());
404        assert_eq!(loaded.nodes.len(), 1);
405        let sum = summary_for_url(dir.path(), "https://example.org/x");
406        assert_eq!(sum["cookie_count"], 1);
407    }
408
409    #[test]
410    fn ga_is_analytics() {
411        assert_eq!(
412            hypothesize_purpose("_ga"),
413            CookiePurposeHypothesis::Analytics
414        );
415    }
416
417    #[test]
418    fn clear_origin_removes_rows() {
419        let dir = tempfile::tempdir().unwrap();
420        let sc = "SID=abc; Domain=example.org; Path=/".to_string();
421        observe_set_cookies(dir.path(), "https://example.org/page", &[sc], 1).unwrap();
422        let r = clear_graph_for_origin(dir.path(), "https://example.org/x").unwrap();
423        assert!(r["removed_graph_nodes"].as_u64().unwrap() >= 1);
424        let g = CookieGraph::load(dir.path());
425        assert!(g.nodes.is_empty());
426    }
427}