add more resources and docs

Author: samfrm

.github/workflows/ci.yml

@@ -8,7 +8,10 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
@@ -18,4 +21,3 @@ jobs:
         run: go build ./...
       - name: Test
         run: go test ./...
-

README.md

@@ -114,6 +114,31 @@ More:
 
 - ⏱️ `--delay` (meta/js, ms), 🔌 `--port` (default 443, falls back to 8443), 🗂️ `--keep-certs`, 🧪 `--no-hosts`, 🧹 `--force-unlock`
 
+### 🔬 Research examples
+
+- Validate experiment gating locally (referrer → experiment route):
+
+```bash
+sudo reflex run \
+  --referrer https://news.google.com \
+  --target   https://localhost:3000/experiment
+```
+
+- Compare redirect methods and observe `document.referrer` differences:
+
+```bash
+sudo reflex run --referrer https://news.google.com --target https://localhost:3000 --method meta
+sudo reflex run --referrer https://news.google.com --target https://localhost:3000 --method js
+sudo reflex run --referrer https://news.google.com --target https://localhost:3000 --method 302
+```
+
+- Evaluate `Referrer-Policy` effects (origin vs full URL):
+
+```bash
+sudo reflex run --referrer https://news.google.com --target https://localhost:3000 --referrer-policy origin-when-cross-origin
+sudo reflex run --referrer https://news.google.com --target https://localhost:3000 --referrer-policy unsafe-url
+```
+
 ### 🩹 Troubleshooting (fast answers)
 
 - 🥚 Empty `document.referrer`?

paper.bib

@@ -3,7 +3,8 @@ @misc{mkcert
   howpublished = {GitHub repository},
   author       = {{FiloSottile}},
   year         = {2018},
-  url          = {https://github.com/FiloSottile/mkcert}
+  url          = {https://github.com/FiloSottile/mkcert},
+  note         = {Accessed 2025-09-16}
 }
 
 @misc{w3c-referrer-policy,
@@ -27,19 +28,48 @@ @misc{mitmproxy
   title        = {mitmproxy: An interactive HTTPS proxy},
   howpublished = {Project website},
   year         = {2025},
-  url          = {https://mitmproxy.org/}
+  url          = {https://mitmproxy.org/},
+  note         = {Accessed 2025-09-16}
 }
 
 @misc{selenium,
   title        = {Selenium WebDriver Project},
   howpublished = {Project website},
   year         = {2025},
-  url          = {https://www.selenium.dev/}
+  url          = {https://www.selenium.dev/},
+  note         = {Accessed 2025-09-16}
 }
 
 @misc{playwright,
   title        = {Playwright},
   howpublished = {Project website},
   year         = {2025},
-  url          = {https://playwright.dev/}
+  url          = {https://playwright.dev/},
+  note         = {Accessed 2025-09-16}
+}
+
+@book{kohavi2020trustworthy,
+  title     = {Trustworthy Online Controlled Experiments: A Practical Guide to A/B Testing},
+  author    = {Kohavi, Ron and Tang, Diane and Xu, Ya},
+  year      = {2020},
+  publisher = {Cambridge University Press},
+  doi       = {10.1017/9781108653985}
+}
+
+@inproceedings{englehardt2016online,
+  title     = {Online tracking: A 1-million-site measurement and analysis},
+  author    = {Englehardt, Steven and Narayanan, Arvind},
+  booktitle = {Proceedings of the 2016 ACM SIGSAC Conference on Computer and Communications Security},
+  year      = {2016},
+  pages     = {1388--1401},
+  doi       = {10.1145/2976749.2978313}
+}
+
+@inproceedings{acar2014never,
+  title     = {The Web Never Forgets: Persistent Tracking Mechanisms in the Wild},
+  author    = {Acar, Gunes and Eubank, Christian and Englehardt, Steven and Juarez, Marc and Narayanan, Arvind and Diaz, Claudia},
+  booktitle = {Proceedings of the 2014 ACM SIGSAC Conference on Computer and Communications Security},
+  year      = {2014},
+  pages     = {674--689},
+  doi       = {10.1145/2660267.2660347}
 }

paper.md

@@ -7,6 +7,7 @@ tags:
   - Measurement
   - Analytics
   - Referrer
+  - Reproducibility
 authors:
   - name: "Sam (Abbas) Farahmand Pashaki"
     orcid: "0009-0006-7721-2644"
@@ -20,9 +21,9 @@ bibliography: paper.bib
 
 # Summary
 
-Browser referrer behavior is central to analytics, experimentation, and attribution pipelines, but it is difficult to reproduce locally. Browsers often suppress `Referer`/`document.referrer` in common local setups (non‑HTTPS origins, external 302 navigations, or OS/browser trust gaps), which prevents meaningful pre‑deployment validation.
+Browser referrer behavior is central to analytics, experimentation, and attribution pipelines, but it is difficult to reproduce locally in a way that is faithful to production and repeatable by other researchers. Browsers often suppress `Referer`/`document.referrer` in common local setups (non‑HTTPS origins, external 302 navigations, or OS/browser trust gaps), which prevents meaningful pre‑deployment validation and undermines the reproducibility of measurement.
 
-Reflex is a small cross‑platform command‑line tool that emulates a realistic referrer locally. It temporarily maps a chosen referrer host to the developer’s machine, serves a trusted HTTPS page with a configurable redirect method, and then navigates to the target application so the browser sets a real `Referer`. Reflex respects the web platform’s referrer policy semantics [@w3c-referrer-policy] and standard HTTP redirection behavior [@rfc9110], and leverages locally trusted certificates via mkcert [@mkcert].
+Reflex is a small cross‑platform command‑line tool that emulates a realistic referrer locally. It temporarily maps a chosen referrer host to the developer’s machine, serves a trusted HTTPS page with a configurable redirect method, and then navigates to the target application so the browser sets a real `Referer`. Reflex respects the web platform’s referrer policy semantics [@w3c-referrer-policy] and standard HTTP redirection behavior [@rfc9110], and leverages locally trusted certificates via mkcert [@mkcert]. This enables researchers and engineers to reproduce and share referrer‑dependent scenarios in a single command, improving the validity of analytics and experiment instrumentation.
 
 # Statement of need
 
@@ -36,6 +37,24 @@ Reflex closes this gap by providing a minimal, reproducible workflow to preview
 
 The tool is intentionally focused: it does not alter browser settings, require extensions, or act as a full proxy. Instead, it uses a short, standards‑compliant HTTPS redirect from a local origin that mimics the selected referrer.
 
+Minimal reproducible example. The following single command reproduces a realistic referrer across OSes using locally trusted HTTPS:
+
+```
+reflex run --referrer https://news.google.com --target https://localhost:3000/experiment
+```
+
+This opens a private/incognito browser window and performs a standards‑conformant redirect so the target observes a populated Referer (e.g., `https://news.google.com/`). The same invocation can be shared to reproduce the scenario on other machines.
+
+
+
+# Use cases for research
+
+- Analytics/attribution validation for controlled experiments: Researchers running online controlled experiments (A/B tests) often need to verify instrumentation and gating rules that depend on referrer context (e.g., arriving from a partner site). Reflex provides a reproducible way to preview and test these flows locally before running or analyzing experiments [@kohavi2020trustworthy].
+- Cross‑browser measurement of `Referrer-Policy` and redirect methods: Web measurement studies can compare how browsers populate `Referer`/`document.referrer` under `meta`, `js`, and `302` redirects with different policies. Reflex enables these controlled tests across OSes with locally trusted TLS [@w3c-referrer-policy; @rfc9110].
+- Privacy and tracking studies: Prior work shows the prevalence and risks of referrer‑based tracking and leakage on the web [@englehardt2016online; @acar2014never]. Reflex can generate reproducible referrer scenarios to validate mitigations (e.g., policy choices) or to build small‑scale datasets illustrating leakage conditions.
+
+Expected impact. While seemingly narrow, reliable referrer emulation is a recurring prerequisite for trustworthy analytics, A/B testing, and privacy measurement. Reflex lowers the setup cost for these workflows and makes them repeatable across environments, which can reduce instrumentation regressions and improve the integrity of subsequent analyses [@kohavi2020trustworthy].
+
 # Functionality
 
 Reflex provides a single binary with three subcommands:
@@ -52,17 +71,30 @@ Key implementation details:
 - A simple file lock avoids concurrent runs from clobbering hosts entries.
 - Cross‑platform browser launchers drop elevated privileges where appropriate so the browser opens in the user’s desktop session (Linux/macOS), with optional private/incognito flags.
 
+# Limitations and scope
+
+Reflex is intentionally narrow in scope:
+
+- Not a proxy or MITM: it does not intercept traffic or modify requests beyond serving a short redirect.
+- Local emulation only: it is designed for local testing, not production spoofing of referrers.
+- No browser reconfiguration: it avoids changing browser settings, profiles, or policies.
+- Subject to site controls: site‑specific defenses (e.g., CSP, framebusting) remain in effect.
+
 # Quality control
 
-The repository includes unit tests for the HTTPS redirector (verifying method‑specific behavior and `Referrer-Policy` headers), hosts file management (add/remove, idempotency, bulk cleanup), local locking, and mkcert detection. Continuous Integration builds and runs tests on Linux via GitHub Actions.
+The repository includes unit tests for the HTTPS redirector (verifying method‑specific behavior and `Referrer-Policy` headers), hosts file management (add/remove, idempotency, bulk cleanup), local locking, and mkcert detection. Tests generate ephemeral self‑signed certificates (no mkcert required) to isolate server behavior. Continuous Integration builds and runs tests on Linux, macOS, and Windows via GitHub Actions.
 
 # State of the field
 
-Developers commonly rely on ad‑hoc local servers, browser extensions, or general‑purpose proxies (e.g., mitmproxy [@mitmproxy]) to test web behavior. Automation frameworks such as Selenium [@selenium] and Playwright [@playwright] can orchestrate browser flows, but they do not specifically target reproducible referrer emulation with locally trusted HTTPS and precise `Referrer-Policy` control out‑of‑the‑box. Reflex fills this narrow but frequently encountered gap with a single‑purpose, scriptable CLI tailored to referrer‑dependent analytics and experimentation.
+Developers commonly rely on ad‑hoc local servers, browser extensions, or general‑purpose proxies (e.g., mitmproxy [@mitmproxy]) to test web behavior. Automation frameworks such as Selenium [@selenium] and Playwright [@playwright] can orchestrate browser flows, but they do not specifically target reproducible referrer emulation with locally trusted HTTPS and precise `Referrer-Policy` control out‑of‑the‑box. Reflex fills this narrow but frequently encountered gap with a single‑purpose, scriptable CLI tailored to referrer‑dependent analytics and experimentation. Unlike browser extensions and flag‑based overrides, it produces a standards‑conformant HTTPS navigation with a trusted certificate and explicit `Referrer‑Policy`, yielding consistent, shareable results across browsers and OSes.
 
 # Availability
 
-Reflex is implemented in Go and distributed as prebuilt binaries for Linux, macOS, and Windows. Source code and issue tracking are available at: https://github.com/samfrm/reflex. An archival release is available on Zenodo (DOI: https://doi.org/10.5281/zenodo.17081049). This paper refers to version v0.1.3 of the software.
+Reflex is implemented in Go and distributed as prebuilt binaries for Linux, macOS, and Windows. Source code and issue tracking are available at: https://github.com/samfrm/reflex. Reflex is MIT‑licensed (LICENSE: https://github.com/samfrm/reflex/blob/main/LICENSE) and archived per‑version on Zenodo (DOI: https://doi.org/10.5281/zenodo.17081049). This paper refers to version v0.1.3 of the software.
+
+# History and maturity
+
+Reflex packages a pattern I’ve used for years—local HTTPS, a short redirect, and hosts mapping—into a single CLI. I open‑sourced and packaged it recently, which is why the public commit history is short. Compared to the original scripts, the CLI adds: mkcert‑based local trust with a shared CAROOT on Linux (/etc/mkcert), tagged and backed‑up /etc/hosts edits (“# reflex‑managed”), a file lock to prevent concurrent runs, and a browser launcher that drops privileges to open a private window in the user session. The repository includes tests and CI; server tests assert the `Referrer‑Policy` and redirect bodies/headers for `meta`, `js`, and `302` methods. I’m not aware of citations yet due to the recent release, but Reflex directly supports the reproducible analytics/experimentation and privacy measurement workflows described in this paper.
 
 # Acknowledgements