Surface Guard

Surface Guard is a Chrome MV3 privacy research extension for defensive fingerprint reduction. The MVP is intentionally narrow: it starts from an inert install, uses only the storage and scripting permissions, and only requests exact per-site host access after a user adds a protected site.

Authoritative product and engineering scope lives in 01-unified-product-engineering-spec.md.

Purpose

This project is for transparent privacy research and defensive fingerprint reduction. It is designed to help evaluate and reduce unnecessary browser fingerprint entropy on user-approved sites.

It is not an anti-abuse tool. It makes no promise of undetectability, does not hide that browser behavior can be measured, and does not provide platform-specific evasion guidance.

Non-Use

Do not use this project for:

• no anti-sybil bypass
• no risk-control evasion
• no anti-cheat evasion
• no bulk accounts
• no promise of undetectability

Current MVP

• Chrome MV3 manifest with no default host permissions.
• No static content scripts.
• TypeScript, Vite, Vitest, and Playwright configuration.
• Static security gates for manifest permissions, page-boundary hazards, remote scripts, console banners, and network exfil patterns.
• Per-site protected-sites allowlist. Dynamic MAIN world content scripts are registered only for origins in that allowlist after Chrome grants the matching origin permission.
• Canvas and WebGL compatibility protections for fingerprint-like small or hidden canvases.
• Local fingerprint lab with baseline, with-extension, and Markdown/JSON report commands.

Current protection coverage is limited to Canvas and WebGL. Audio, Fonts, Hardware Concurrency, Device Memory, screen metrics, media devices, locale, time zone, and other fingerprint surfaces are not protected by the current MVP unless a future change explicitly adds and tests them.

Development

Install dependencies:

pnpm install

Run the static security gate:

pnpm test:security

Run the full local checks:

pnpm typecheck
pnpm test:unit
pnpm test:security
pnpm test:e2e

Run the fingerprint lab:

pnpm lab:baseline
pnpm lab:with-extension
pnpm lab:report

pnpm lab:with-extension builds and loads the real dist extension by default and may require an interactive Chrome host-access grant for the lab origin. CI requests the same exact lab-origin permission through Chrome's optional permissions API, not fixture injection. Fixture collection is available only as an explicit opt-in with pnpm lab:with-fixture or LAB_EXTENSION_FIXTURE=main-world. The lab writes deterministic JSON and Markdown reports under lab/output/. It records probe hashes and pass/fail summaries, not raw fingerprint values.

Security Boundaries

Fresh installs must remain inert: no default host_permissions, no web_accessible_resources, no static content_scripts, no global content-script registration, and no external network behavior. Future protection code must keep seed, salt, and policy data out of the DOM, window, page messages, URLs, page storage, and console output.

See docs/privacy-boundaries.md, docs/acceptable-use.md, and docs/measurement.md.