Technical Guide

Browser Integrity

Bridging the gap between the sandboxed web and hardware truth.

The Browser Sandbox Problem

Modern web browsers (Chrome, Safari, Firefox) are designed with a "sandbox" security model. While this protects users from malicious websites, it also creates a significant obstacle for high-compliance applications. Browsers provide very limited access to hardware signals—such as raw GPS data, WiFi BSSID scans, or hardware-backed device attestation.

For regulated industries like iGaming and Fintech, standard browser signals are insufficient. They are easily spoofed using "Sensor Providers" or browser developer tools. Peabody Compliance solves this by performing a secure handover from the browser to native hardware agents, ensuring that location data is anchored in physical truth rather than software simulation.

How the Handover Works

The Peabody JS SDK implements a "Layered Resilience" strategy to move the user from a browser-based session to a native verification environment and back again, seamlessly.

1. Detection & Protocol Selection

When Peabody.verifySession() is called, the SDK first analyzes the user's environment to determine the most secure path:

  • iOS: Uses a peabodyverify:// Deep Link.
  • Android: Uses a intent:// Chrome Intent URL (or Deep Link fallback).
  • Desktop: Communicates with the local Peabody Agent via a secure localhost bridge.

2. The Handover Loop

On mobile, the SDK triggers the native app. To ensure the user is never stuck, the SDK employs a visibility-based fallback timer:

  1. The SDK fires the link to open the Peabody Verify App.
  2. A 2.5-second timer starts.
  3. If the app opens, the browser moves to the background (document.hidden becomes true), and the SDK resolves the session.
  4. If the browser remains visible (meaning the app isn't installed), the timer expires and the SDK automatically redirects the user to the appropriate installation landing page.

3. Verification & Redirect

Once the Verify App completes its hardware-level checks, it receives a signed token from our API. It then uses the returnUrl provided by the SDK to redirect the user back to the original website, appending a peabody_verified=1 parameter to the URL. The SDK detects this parameter, cleans the URL from the browser history, and returns a "Success" result to your application logic.

Browser Compatibility

Peabody is engineered to work across the entire modern browser ecosystem, including privacy-focused and non-standard browsers.

Browser Platform Support Status Notes
Safari iOS Native Full support via Deep Links.
Chrome Android / iOS Native Uses Intent URLs for seamless Android handover.
DuckDuckGo Mobile / Desktop Full Works via the 2.5s fallback mechanism.
Brave Mobile Full Handles custom schemes similarly to Chrome.
Firefox Android Resilient Uses the JS fallback timer for app detection.
Safari macOS Unsupported Blocks localhost connection. Chrome or Firefox required.

The Desktop "Localhost" Challenge

Critical Limitation

Desktop Safari is currently not compatible with the Peabody Compliance Agent. If your application requires high-integrity hardware verification, users on macOS must use Chrome, Firefox, or Edge.

On macOS and Windows, Peabody uses a lightweight desktop agent to perform WiFi triangulation and VPN detection. The JS SDK communicates with this agent via a local HTTP bridge (http://localhost:12180).

The Safari Exception

Desktop Safari implements a strict security policy that prevents HTTPS websites from communicating with localhost over unencrypted HTTP. Unlike Chrome or Firefox, Safari does not provide a mechanism to allow this local "loopback" connection from a secure web origin.

Resolution: For high-compliance tasks on Mac, the Peabody SDK automatically detects Safari and advises the user to switch to Chrome, Edge, or Firefox. Once the user opens the same URL in a supported browser, the Peabody Agent will respond instantly.

Privacy & Security

Peabody's browser handover is designed with a "Privacy First" architecture:

  • No Persistent Tracking: We do not use cookies or browser fingerprinting to track users across sites. Each verification is a discrete event.
  • Signed Tokens: The handover between the browser and app is protected by cryptographically signed tokens (using HMAC SHA-256). An attacker cannot forge a "Success" result by manually navigating to the peabody_verified URL.
  • Sandboxed Data: The native Verify App only accesses the minimum required hardware signals to perform the requested check.

Conclusion

By bridging the browser to native hardware, Peabody Compliance provides a level of integrity that standard web applications simply cannot achieve. Our layered approach ensures that whether your user is on the latest iPhone using Safari or an older Android device using DuckDuckGo, the verification process is secure, resilient, and compliant.

For more technical details on integrating the SDK, visit our Documentation.