Tracking protection

​

Overview

​

How tracking protection works

​

Two-layer protection

1. Content rule lists: Block known tracking domains and resources using WebKit’s WKContentRuleList API
2. Third-party cookie script: Prevent cross-site iframes from accessing document.cookie and Storage Access API

​

Content blocking

• Third-party cookie blocking: Attempts to block all cookies loaded from third-party contexts
• Tracker domain blocking: Blocks requests to known tracking domains
• Fallback mode: If cookie blocking is unsupported, falls back to domain-only blocking

​

JavaScript-based cookie blocking

// From TrackingProtectionManager.swift:22-50
(function() {
  // Only act in embedded contexts
  if (window.top === window) return;
  
  // Check if this is a third-party iframe
  var ref = document.referrer || "";
  var thirdParty = false;
  try {
    var refHost = ref ? new URL(ref).hostname : null;
    thirdParty = !!refHost && refHost !== window.location.hostname;
  } catch (e) { thirdParty = false; }
  if (!thirdParty) return;
  
  // Neuter document.cookie in third-party contexts
  Object.defineProperty(document, 'cookie', {
    configurable: false,
    enumerable: false,
    get: function() { return ''; },
    set: function(_) { return true; }
  });
  
  // Deny Storage Access API
  document.requestStorageAccess = function() {
    return Promise.reject(new DOMException('Blocked by Nook', 'NotAllowedError'));
  };
})();

• Only activates in embedded iframes (not main frames)
• Checks if the iframe is cross-site using document.referrer
• Overrides document.cookie to return empty string and ignore writes
• Blocks the Storage Access API with a rejected promise

​

Blocked tracking domains

​

Analytics and tracking

• google-analytics.com
• analytics.google.com
• googletagmanager.com
• googletagservices.com
• doubleclick.net
• hotjar.com
• segment.io / cdn.segment.com
• mixpanel.com
• optimizely.com
• clarity.ms

​

Social media trackers

• facebook.net
• connect.facebook.net
• graph.facebook.com

​

Ad networks

• adsystem.com
• adservice.google.com

​

Error tracking

• sentry.io
• newrelic.com

​

Exceptions and allowlisting

​

Per-domain allowlist

// From TrackingProtectionManager.swift:86-98
func allowDomain(_ host: String, allowed: Bool = true) {
    let norm = host.lowercased()
    if allowed { allowedDomains.insert(norm) } else { allowedDomains.remove(norm) }
    
    // Update existing tabs for this host
    for tab in browserManager.tabManager.allTabs() {
        if tab.webView?.url?.host?.lowercased() == norm {
            if allowed { removeTracking(from: wv) } else { applyTracking(to: wv) }
            wv.reloadFromOrigin()
        }
    }
}

• Tracking protection is disabled for that domain
• All existing tabs on that domain are updated and reloaded
• The domain remains allowed until you revoke it

​

Temporary disabling

​

OAuth flow exemption

// From TrackingProtectionManager.swift:203-210
private func shouldApplyTracking(to tab: Tab) -> Bool {
    if !isEnabled { return false }
    if isTemporarilyDisabled(tabId: tab.id) { return false }
    if isDomainAllowed(tab.webView?.url?.host) { return false }
    // Never apply tracking protection to OAuth flow tabs
    if tab.isOAuthFlow { return false }
    return true
}

• accounts.google.com
• login.microsoftonline.com
• github.com/login
• And other OAuth providers

​

Enabling tracking protection

​

Disabling tracking protection

1. Content rule lists are removed from the shared configuration
2. The third-party cookie script is removed from user scripts
3. All existing webviews have tracking protection removed
4. All tabs are reloaded from origin to apply changes

​

Configuration details

​

Rule list compilation

• Rules are compiled once and cached on disk
• On subsequent launches, Nook looks up the cached compiled list
• If cookie blocking fails to compile (unsupported action), Nook falls back to domain-only blocking
• Rules are identified by "NookTrackingBlocker" (or "NookTrackingBlocker.fallback" for fallback mode)

​

Shared vs. per-webview configuration

​

Shared configuration

• Rule lists are added to userContentController
• User script is injected at document start
• New tabs automatically inherit these settings

​

Per-webview application

• Each tab’s webview configuration is checked
• Tracking protection is applied or removed based on tab state
• Webview is reloaded from origin to ensure rules take effect

​

Refresh and updates

// From TrackingProtectionManager.swift:231-239
func refreshFor(tab: Tab) {
    guard let wv = tab.webView else { return }
    if shouldApplyTracking(to: tab) {
        applyTracking(to: wv)
    } else {
        removeTracking(from: wv)
    }
    wv.reloadFromOrigin()
}

• Tab state changes (e.g., becomes an OAuth flow)
• Domain is added to or removed from allowlist
• Temporary exemption expires

​

Limitations and compatibility

​

Known limitations

1. Cookie blocking action: The block-cookies action may not be supported on all macOS versions. Nook falls back to domain blocking if compilation fails.
2. First-party trackers: Tracking protection only blocks third-party requests. First-party analytics (same domain as the site) are not blocked.
3. Fingerprinting: Tracking protection doesn’t prevent browser fingerprinting techniques that don’t rely on cookies or scripts.
4. Network-level tracking: Your ISP, employer, or network administrator can still monitor your browsing regardless of tracking protection.

​

Compatibility considerations

• Social media embeds: Facebook, Twitter, and other social widgets may not load with tracking protection enabled
• Embedded videos: YouTube and Vimeo embeds may require third-party cookies
• Payment processors: Checkout flows using embedded payment forms may need exemptions
• Single sign-on: Some SSO implementations may break; OAuth flows are auto-exempted

​

Technical implementation

​

Manager lifecycle

func attach(browserManager: BrowserManager) {
    self.browserManager = browserManager
}

​

Rule JSON structure

[
  {
    "trigger": {
      "url-filter": ".*",
      "load-type": ["third-party"]
    },
    "action": { "type": "block-cookies" }
  },
  {
    "trigger": { "url-filter": "google-analytics\\.com" },
    "action": { "type": "block" }
  }
]

• trigger: Specifies when the rule applies (URL pattern, load type)
• action: What to do when triggered (block, block-cookies, etc.)

​

State tracking

• isEnabled: Global on/off toggle
• installedRuleList: Compiled WKContentRuleList instance
• temporarilyDisabledTabs: Map of tab ID → expiration date for temporary exemptions
• allowedDomains: Set of domains permanently exempted from tracking protection

​

Best practices