chore: missed files

harlan-zw · harlan-zw · commit 0485d593c3b3 · 2026-02-18T19:09:11.000+11:00
diff --git a/docs/content/docs/1.guides/2.first-party.md b/docs/content/docs/1.guides/2.first-party.md
@@ -16,7 +16,8 @@ When third-party scripts load directly from external servers, they expose your u
 
 First-party mode routes all script traffic through your domain:
 
-- **User IPs stay private** - Third parties see your server's IP, not your users'
+- **User IPs anonymized** - IPs are anonymized to subnet level before forwarding; third parties can't identify individual users
+- **Device fingerprinting reduced** - Screen resolution, User-Agent, and hardware info are generalized to common buckets
 - **No third-party cookies** - Requests are same-origin, eliminating cross-site tracking
 - **Works with ad blockers** - Requests appear first-party
 - **Faster loads** - No extra DNS lookups for external domains
@@ -52,6 +53,29 @@ export default defineNuxtConfig({
 })
 ```
 
+### Privacy Modes
+
+First-party mode supports two privacy levels via the `privacy` option:
+
+| Mode | Description |
+|------|-------------|
+| `'anonymize'` (default) | Anonymizes IP addresses to subnet level, generalizes screen resolution and hardware info to common buckets, normalizes User-Agent to browser family + major version. Analytics IDs are preserved so tracking still works. |
+| `'proxy'` | Forwards requests as-is through your server. Strips sensitive headers (cookies, authorization) but doesn't modify analytics payloads. Privacy comes from third parties seeing your server's IP instead of the user's. |
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    firstParty: {
+      privacy: 'proxy', // or 'anonymize' (default)
+    }
+  }
+})
+```
+
+::callout{type="info"}
+In `anonymize` mode, fingerprinting data is **generalized** rather than stripped — analytics endpoints still receive valid data, just with reduced precision. For example, screen resolution `1440x900` becomes `1920x1080` (desktop bucket), and User-Agent is normalized to `Mozilla/5.0 (compatible; Chrome/131.0)`.
+::
+
 ### Custom Paths
 
 Customize the proxy endpoint paths:
@@ -83,15 +107,15 @@ useScriptGoogleAnalytics({
 
 First-party mode supports the following scripts:
 
-| Script | Endpoints Routed |
-|--------|------------------|
-| Google Analytics | `www.google.com/g/collect`, `www.google-analytics.com` |
+| Script | Endpoints Proxied |
+|--------|-------------------|
+| Google Analytics | `google-analytics.com`, `analytics.google.com`, `stats.g.doubleclick.net`, `pagead2.googlesyndication.com` |
 | Google Tag Manager | `www.googletagmanager.com` |
-| Meta Pixel | `connect.facebook.net`, `www.facebook.com/tr` |
+| Meta Pixel | `connect.facebook.net`, `www.facebook.com/tr`, `pixel.facebook.com` |
 | TikTok Pixel | `analytics.tiktok.com` |
 | Segment | `api.segment.io`, `cdn.segment.com` |
-| Microsoft Clarity | `www.clarity.ms` |
-| Hotjar | `static.hotjar.com`, `vars.hotjar.com` |
+| Microsoft Clarity | `www.clarity.ms`, `scripts.clarity.ms`, `d.clarity.ms`, `e.clarity.ms` |
+| Hotjar | `static.hotjar.com`, `script.hotjar.com`, `vars.hotjar.com`, `in.hotjar.com` |
 | X/Twitter Pixel | `analytics.twitter.com`, `t.co` |
 | Snapchat Pixel | `tr.snapchat.com` |
 | Reddit Pixel | `alb.reddit.com` |
diff --git a/docs/content/scripts/analytics/google-analytics.md b/docs/content/scripts/analytics/google-analytics.md
@@ -192,8 +192,8 @@ This script supports [First-Party Mode](/docs/guides/first-party) which routes a
 When enabled globally via `scripts.firstParty: true`, this script will:
 - Load from your domain instead of third-party servers
 - Route collection requests (`/g/collect`) through your server
-- Hide user IP addresses from Google
-- Strip fingerprinting parameters (`sr`, `vp`, `sd`, `ul`)
+- Anonymize user IP addresses to subnet level
+- Generalize device fingerprinting data (`sr`, `vp`, `ul`) to common buckets
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
diff --git a/docs/content/scripts/marketing/clarity.md b/docs/content/scripts/marketing/clarity.md
@@ -131,9 +131,9 @@ This script supports [First-Party Mode](/docs/guides/first-party) which routes a
 
 When enabled globally via `scripts.firstParty: true`, this script will:
 - Load from your domain instead of `www.clarity.ms`
-- Route data/event collection through your server
-- Hide user IP addresses from Microsoft
-- Strip fingerprinting parameters from session data
+- Route data/event collection (`d.clarity.ms`, `e.clarity.ms`) through your server
+- Anonymize user IP addresses to subnet level
+- Generalize device fingerprinting data to common buckets
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
diff --git a/docs/content/scripts/marketing/hotjar.md b/docs/content/scripts/marketing/hotjar.md
@@ -117,9 +117,9 @@ This script supports [First-Party Mode](/docs/guides/first-party) which routes a
 
 When enabled globally via `scripts.firstParty: true`, this script will:
 - Load from your domain instead of `static.hotjar.com`
-- Route configuration and data requests through your server
-- Hide user IP addresses from Hotjar
-- Strip device fingerprinting parameters
+- Route configuration and data requests (`vars.hotjar.com`, `in.hotjar.com`) through your server
+- Anonymize user IP addresses to subnet level
+- Generalize device fingerprinting data to common buckets
 
 ::callout{type="info"}
 Hotjar uses WebSocket connections for session recording data. The proxy handles initial setup, but WebSocket connections go directly to Hotjar servers.
diff --git a/docs/content/scripts/tracking/google-tag-manager.md b/docs/content/scripts/tracking/google-tag-manager.md
@@ -265,8 +265,8 @@ This script supports [First-Party Mode](/docs/guides/first-party) which routes a
 When enabled globally via `scripts.firstParty: true`, this script will:
 - Load from your domain instead of `www.googletagmanager.com`
 - Route all GTM requests through your server
-- Hide user IP addresses from Google
-- Strip fingerprinting parameters
+- Anonymize user IP addresses to subnet level
+- Generalize device fingerprinting data to common buckets
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
diff --git a/docs/content/scripts/tracking/meta-pixel.md b/docs/content/scripts/tracking/meta-pixel.md
@@ -154,8 +154,8 @@ This script supports [First-Party Mode](/docs/guides/first-party) which routes a
 When enabled globally via `scripts.firstParty: true`, this script will:
 - Load from your domain instead of `connect.facebook.net`
 - Route tracking requests (`/tr`) through your server
-- Hide user IP addresses from Meta
-- Strip fingerprinting parameters (`ud`, `fbp`, `fbc`, `external_id`)
+- Anonymize user IP addresses to subnet level
+- Generalize device fingerprinting data to common buckets
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
diff --git a/docs/content/scripts/tracking/reddit-pixel.md b/docs/content/scripts/tracking/reddit-pixel.md
@@ -123,8 +123,8 @@ This script supports [First-Party Mode](/docs/guides/first-party) which routes a
 When enabled globally via `scripts.firstParty: true`, this script will:
 - Load from your domain instead of `alb.reddit.com`
 - Route tracking requests through your server
-- Hide user IP addresses from Reddit
-- Strip fingerprinting parameters
+- Anonymize user IP addresses to subnet level
+- Generalize device fingerprinting data to common buckets
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
diff --git a/docs/content/scripts/tracking/segment.md b/docs/content/scripts/tracking/segment.md
@@ -125,8 +125,8 @@ This script supports [First-Party Mode](/docs/guides/first-party) which routes a
 When enabled globally via `scripts.firstParty: true`, this script will:
 - Load from your domain instead of `cdn.segment.com`
 - Route API requests (`api.segment.io`) through your server
-- Hide user IP addresses from Segment
-- Strip fingerprinting parameters (`anonymousId`, `context.ip`, `context.userAgent`)
+- Anonymize user IP addresses to subnet level
+- Normalize User-Agent and generalize device fingerprinting data to common buckets
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
diff --git a/docs/content/scripts/tracking/snapchat-pixel.md b/docs/content/scripts/tracking/snapchat-pixel.md
@@ -181,8 +181,8 @@ This script supports [First-Party Mode](/docs/guides/first-party) which routes a
 When enabled globally via `scripts.firstParty: true`, this script will:
 - Load from your domain instead of `tr.snapchat.com`
 - Route tracking requests through your server
-- Hide user IP addresses from Snapchat
-- Strip fingerprinting parameters (`d_a`, `d_ot`, `d_os`, `d_bvs`, screen dimensions)
+- Anonymize user IP addresses to subnet level
+- Generalize device fingerprinting data (`d_os`, `d_bvs`, screen dimensions) to common buckets
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
diff --git a/docs/content/scripts/tracking/tiktok-pixel.md b/docs/content/scripts/tracking/tiktok-pixel.md
@@ -140,8 +140,8 @@ This script supports [First-Party Mode](/docs/guides/first-party) which routes a
 When enabled globally via `scripts.firstParty: true`, this script will:
 - Load from your domain instead of `analytics.tiktok.com`
 - Route tracking requests through your server
-- Hide user IP addresses from TikTok
-- Strip fingerprinting parameters
+- Anonymize user IP addresses to subnet level
+- Generalize device fingerprinting data to common buckets
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
diff --git a/docs/content/scripts/tracking/x-pixel.md b/docs/content/scripts/tracking/x-pixel.md
@@ -144,8 +144,8 @@ This script supports [First-Party Mode](/docs/guides/first-party) which routes a
 When enabled globally via `scripts.firstParty: true`, this script will:
 - Load from your domain instead of `analytics.twitter.com`
 - Route tracking requests (`t.co`) through your server
-- Hide user IP addresses from X/Twitter
-- Strip fingerprinting parameters (`dv`, `bci`, `eci`, `pl_id`, `p_user_id`)
+- Anonymize user IP addresses to subnet level
+- Generalize device fingerprinting data (`dv` combined device info) to common buckets
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
diff --git a/test/e2e/first-party.test.ts b/test/e2e/first-party.test.ts
@@ -349,7 +349,7 @@ function extractRequestDiff(capture: Record<string, any>): Record<string, any> {
   json = json.replace(/:17\d{11,}([,}\]])/g, ':"<TS_MS>"$1')
   json = json.replace(/"17\d{11,}"/g, '"<TS_MS>"')
   // Normalize long base64-like session tokens (Snapchat si, etc.)
-  json = json.replace(/"si":"[\w\-]{40,}"/g, '"si":"<SESSION_TOKEN>"')
+  json = json.replace(/"si":"[\w-]{40,}"/g, '"si":"<SESSION_TOKEN>"')
   // Normalize volatile numeric arrays (Snapchat timing/perf data)
   json = json.replace(/"a":\[[\d,\s]+\]/g, '"a":"<TIMING>"')
   json = json.replace(/"p":\[[\d,\s]+\]/g, '"p":"<PERF>"')
diff --git a/test/fixtures/first-party/proxy-test.json b/test/fixtures/first-party/proxy-test.json
diff --git a/test/fixtures/first-party/sw-status.json b/test/fixtures/first-party/sw-status.json
@@ -3,7 +3,7 @@
     "supported": true,
     "registrations": [
       {
-        "scope": "http://127.0.0.1:37591/",
+        "scope": "http://127.0.0.1:44373/",
         "active": "activated"
       }
     ],
