sovereign_browser_rust/plans/browser-fingerprint-spoofing.md

# Browser Fingerprint Spoofing (Desktop + Mobile)

## Goal

Let sovereign_browser present itself as a different browser — Chrome, Firefox,
Safari, Edge, and mobile browsers (Chrome Android, Safari iOS, Samsung
Internet, Firefox Android) — at both the **User-Agent string** level and the
**JavaScript fingerprint** level, so sites and scripts see a consistent
impersonated browser.

## Scope

- **In scope:** UA string, `navigator.*` overrides, `navigator.userAgentData`
  (Client Hints JS API), `screen.*`, `devicePixelRatio`, WebGL
  vendor/renderer, touch points, languages, and (optionally) `Sec-CH-UA*`
  request headers.
- **Out of scope (documented as caveats):** TLS/JA3/JA4 fingerprints, HTTP/2
  frame fingerprints, and true engine-level differences. WebKitGTK remains the
  engine; this is UA + JS-surface spoofing only.

## Architecture

```mermaid
flowchart TD
    A[Settings UI sovereign://settings] --> B[Bridge settings/set]
    B --> C[BrowserSettings store]
    C --> D[fingerprint module resolve]
    D --> E[FingerprintProfile]
    E --> F[WebKit Settings set_user_agent]
    E --> G[UserContentManager injected JS]
    E --> H[Optional Sec-CH-UA request headers]
    F --> I[WebView]
    G --> I
    H --> I
```

## Data Model

New module `src/fingerprint.rs`:

```rust
pub struct FingerprintProfile {
    pub id: String,
    pub label: String,
    pub category: Category,      // Desktop | Mobile | Bot | Custom
    pub user_agent: String,
    pub platform: String,        // navigator.platform
    pub vendor: String,          // navigator.vendor
    pub app_version: String,     // navigator.appVersion
    pub oscpu: Option<String>,   // navigator.oscpu (Firefox)
    pub product_sub: String,     // navigator.productSub
    pub ua_brands: Vec<(String, String)>, // userAgentData.brands
    pub ua_mobile: bool,         // userAgentData.mobile
    pub ua_platform: String,     // userAgentData.platform
    pub hardware_concurrency: u32,
    pub device_memory: u32,
    pub max_touch_points: u32,   // 0 desktop, 5 mobile
    pub screen: ScreenInfo,      // width/height/avail/colorDepth/pixelDepth
    pub device_pixel_ratio: f64,
    pub languages: Vec<String>,
    pub webgl_vendor: String,
    pub webgl_renderer: String,
}
```

`resolve(settings) -> Option<FingerprintProfile>` returns the active profile
from `user_agent_mode` (`default` | `preset` | `custom`), or `None` when
spoofing is off.

## Preset Catalog

Built-in presets, grouped by category:

- **Desktop:** Chrome (Windows/macOS/Linux), Firefox (Windows/macOS/Linux),
  Safari (macOS), Edge (Windows).
- **Mobile:** Chrome Android, Safari iOS (iPhone), Safari iOS (iPad),
  Samsung Internet (Android), Firefox Android.
- **Bots:** Googlebot, Bingbot.

Each preset carries a fully consistent set of values (UA string, platform,
vendor, brands, screen size, DPR, touch points, WebGL strings) so the spoofed
surface does not contradict itself.

## Injection Strategy

1. **UA string (engine level):** call `Settings::set_user_agent(Some(ua))` on
   each tab's `WebKitSettings` in `tab_manager_new_tab()`.
2. **JS surface (main world, document-start):** new
   `www/js/fingerprint-spoof.js` embedded via `include_str!`, plus a small
   preamble that sets `window.__SB_FP = { ...profile json... }`. Added to the
   tab's `UserContentManager` before the webview is built. A preamble guard
   skips `sovereign:` pages (same pattern as the perf probe) so internal pages
   are unaffected.
3. **Overrides applied by the script:**
   - `navigator.userAgent`, `appVersion`, `platform`, `vendor`, `productSub`,
     `oscpu`, `hardwareConcurrency`, `deviceMemory`, `maxTouchPoints`,
     `language`, `languages`
   - `navigator.userAgentData` (brands, mobile, platform, and
     `getHighEntropyValues`)
   - `screen.width/height/availWidth/availHeight/colorDepth/pixelDepth`,
     `window.devicePixelRatio`
   - `WebGLRenderingContext.prototype.getParameter` and
     `WebGL2RenderingContext.prototype.getParameter` for
     `UNMASKED_VENDOR_WEBGL` (37445) and `UNMASKED_RENDERER_WEBGL` (37446)
   - `'ontouchstart' in window` and `navigator.maxTouchPoints` for mobile
   - `Intl.DateTimeFormat().resolvedOptions().timeZone` (optional)
4. **Optional request headers:** `WebView::connect_send_request` to add
   `Sec-CH-UA`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Platform` so HTTP-level Client
   Hints match the JS surface.

## Settings & Persistence

Add to `BrowserSettings` (`src/settings.rs`):

- `fingerprint_spoof_enabled: bool` (default `false`)
- `user_agent_mode: String` (default `"default"`)
- `user_agent_preset: String` (default `""`)
- `user_agent_custom: String` (default `""`)

Update `Default`, `settings_update`, `settings_save`, and `settings_load`.
Include the fields in the NIP-78 payload in `src/settings_sync.rs`.

## Bridge API (`src/nostr_bridge.rs`)

- `handle_settings_config_json`: add `fingerprint_spoof_enabled`,
  `user_agent_mode`, `user_agent_preset`, `user_agent_custom`, and a
  `user_agent_presets` array (`id`, `label`, `category`, `ua`) for the UI.
- `handle_settings_set`:
  - feature toggle `fingerprint_spoof_enabled`
  - keys `user_agent_mode`, `user_agent_preset`, `user_agent_custom`
  - on change, reload open tabs so the new identity takes effect
    (add `tab_manager_reload_all_tabs()`).

## Settings UI (`www/settings.html`, `www/settings.js`)

New **Browser Identity** section:

- Master toggle: "Spoof browser fingerprint"
- Preset dropdown, grouped by Desktop / Mobile / Bots / Custom
- Custom UA text input (enabled when Custom is selected)
- Link to a fingerprint test page (e.g. browserleaks.com)

`applyConfig` populates the controls; `toggle`/`save` call the bridge.

## Optional Enhancements

- Hamburger menu submenu "Browser Identity" with radio items for quick preset
  switching (`src/tab_manager.rs` `build_hamburger_menu`).
- Internal debug page `sovereign://fingerprint` showing the active spoofed
  values for verification.

## Deferred

- **Plan item 9 — `Sec-CH-UA*` request headers (deferred).** Sending
  `Sec-CH-UA`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Platform` (and the high-entropy
  variants) on subresource requests is not implemented. WebKitGTK's UI process
  cannot modify subresource request headers: `WebView::connect_send_request`
  only fires for the main resource, and there is no UI-process API to rewrite
  headers for subresources. Doing this correctly requires a **web-process
  extension** (a `WebKitWebProcessExtension` loaded into the WebProcess) that
  intercepts requests there. Until then the HTTP-level Client Hints do not
  match the JS `navigator.userAgentData` surface, which is itself a
  fingerprinting signal — documented as a known limitation in
  `www/js/fingerprint-spoof.js`.

## Caveats

- Engine-level fingerprints (TLS, HTTP/2, JS engine quirks) still identify
  WebKitGTK; this feature spoofs the UA and JS-visible surface only.
- All spoofed values must stay internally consistent; inconsistent presets are
  themselves a fingerprinting signal.
- Mobile spoofing changes JS-visible values, not the actual rendering viewport.

## Testing

- Verify against browserleaks.com, whatismybrowser.com, and a Client Hints
  test page for each preset (desktop + mobile).
- Confirm `navigator.userAgent` matches the `Sec-CH-UA` headers and the
  engine-level UA.
- Confirm internal `sovereign://` pages are unaffected.
- Confirm settings persist across restart and sync via NIP-78.

## File-by-File Change List

- `src/fingerprint.rs` (new) — profile model, preset catalog, resolve, JS config
- `src/lib.rs`, `src/main.rs` — register module
- `src/settings.rs` — new fields, defaults, update/save/load
- `src/settings_sync.rs` — include new fields in payload
- `src/web_context.rs` — apply UA string in settings configuration
- `src/nostr_inject.rs` — add fingerprint script to content manager
- `www/js/fingerprint-spoof.js` (new) — JS overrides
- `src/tab_manager.rs` — wire UA + injection into tab creation; reload-all helper
- `src/nostr_bridge.rs` — config JSON + set handlers
- `www/settings.html`, `www/settings.js` — Browser Identity UI

## Implementation status

Phases 1–2 (data layer, UA application, JS injection) are done and reviewed.
Phase 3 (settings UI, bridge wiring, hamburger submenu, debug page) is done.

### Phase 3 fixes from review

- `www/js/fingerprint-spoof.js`: `devicePixelRatio`, `outerWidth` and
  `outerHeight` are now installed as own accessor properties of the `window`
  instance (via a new `defineWindowGetter` helper) instead of on
  `Window.prototype`. In WebKitGTK these are own accessors of the window
  instance, so prototype getters were shadowed and had no effect. The getters
  are still passed through the native-toString masking helper.
- `src/fingerprint.rs`: `chrome-android`, `samsung-internet` and
  `firefox-android` now set `ua_architecture = "arm"` (Android devices report
  "arm"). `deviceMemory` and the Firefox `buildID` were left unchanged.

### Bridge (`src/nostr_bridge.rs`)

- `handle_settings_config_json`: added `fingerprint_spoof_enabled`,
  `user_agent_mode`, `user_agent_preset`, `user_agent_custom`,
  `user_agent_presets` (`presets_json()`) and `active_fingerprint`
  (`serde_json::to_value(resolve(&s))`, or `null`).
- `handle_settings_set`:
  - feature `fingerprint_spoof_enabled` — flips and saves; when turning ON
    while `user_agent_mode == "default"` it also sets the mode to `"preset"`.
  - key `user_agent_mode` — validates `default|preset|custom` (else 400).
  - key `user_agent_preset` — validates via `preset_by_id` (else 400
    "Unknown preset"); also sets `user_agent_mode = "preset"`.
  - key `user_agent_custom` — trims; also sets `user_agent_mode = "custom"`
    when non-empty.
  - All of the above schedule `tab_manager_apply_fingerprint_all()` with
    `glib::idle_add_local_once(...)` (never inline — we are inside a
    URI-scheme request callback and must not reload webviews mid-request).
    Response is `{key, value}` with no `reload` flag.
- New `handle_fingerprint_data_json` for `sovereign://fingerprint/data`.

### Settings UI (`www/settings.html`, `www/settings.js`)

- New "Browser Identity" section (after Search, before Network): master toggle
  (`data-feature="fingerprint_spoof_enabled"`), grouped preset `<select>`
  (`Desktop`/`Mobile`/`Bots` optgroups + `Custom…`), custom-UA input row
  (shown only for `Custom…`), read-only "Active User-Agent" line, and a
  "View details" link to `sovereign://fingerprint`.
- `applyConfig` adds `fingerprint_spoof_enabled` to `toggleMap` and calls the
  new `renderIdentity(d)`; `saveIdentity()` / `saveCustomUA()` call the bridge
  and then `refreshConfig()` (re-fetch + `applyConfig`, no full reload);
  `updateCustomRowVisibility()` toggles the custom row; controls are disabled
  (but visible) when spoofing is off.

### Hamburger submenu (`src/tab_manager.rs`)

- `build_hamburger_menu` adds a "Browser Identity" submenu in the Network
  group. Contents are rebuilt lazily on `connect_show` (like Recents/Bookmarks)
  so the checked state is always current. Radio items are all in one group;
  the active state is set before `toggled` is connected, so building the menu
  never fires an action. Helpers: `identity_add_radio` and `identity_apply`
  (persists settings, then
  `glib::idle_add_local_once(tab_manager_apply_fingerprint_all)`).

### Debug page `sovereign://fingerprint`

- New `www/fingerprint.html`, `www/fingerprint.css`, `www/fingerprint.js`,
  registered in `src/embedded_web_content.rs` (`get_fingerprint_html`,
  `WWW_FINGERPRINT_CSS`, `WWW_FINGERPRINT_JS`, and the `get_content_with_mime`
  match arms). The `fingerprint/data` route is dispatched in
  `handle_sovereign_scheme` (`src/nostr_bridge.rs`).
- The page shows status, a spoofed-vs-real comparison table (the real column is
  read live from the unspoofed `sovereign://` page), known limitations, and
  links to browserleaks / whatismybrowser / creepjs.

### Verification

- `cargo build` — clean, no warnings.
- `cargo test` — 38 passed, 0 failed.
- `node --check www/settings.js`, `node --check www/fingerprint.js`, and
  `node --check` on a temp copy of `www/js/fingerprint-spoof.js` (with `({});`
  appended) — all pass.