Peabody Compliance SDK

Integrate sub-second location integrity and hardware-backed device verification into your mobile and web applications.

Installation

The Peabody SDK for iOS is distributed as a Swift Package. You can add it to your project in Xcode by pointing to our release repository.

https://github.com/PeabodySecure/PeabodySDK-Release

Configuration

The Peabody SDK supports multiple authentication methods depending on your security architecture. Choose one of the following methods to initialize the SDK early in your app lifecycle (e.g., in AppDelegate or your main App struct).

Method 1: Hardcoded API Key

Use this method if you wish to bundle your API key directly within the application.

import PeabodySDK

Peabody.configure(apiKey: "your_api_key_here")

Method 2: Client ID Handshake (Recommended)

Use this method to exchange a public Client ID for a temporary session token. This avoids embedding your sensitive API key in the binary. You can configure this via code or Info.plist.

// Option A: Configure via code
Peabody.configure(clientId: "your_client_id_here")

// Option B: Add 'PeabodyClientID' to your Info.plist
// The SDK will automatically perform the handshake on the first verification.

Debug Logging

During development, you can enable verbose console logging to inspect hardware signals and network handshakes.

Peabody.enableDebugLogging()

Requesting Permissions

Peabody requires location permissions to perform jurisdictional checks. You can request "When In Use" or "Always" access using our helper methods.

Peabody.requestWhenInUsePermission { status in
    print("Location status: \(status)")
}

Customer Tracking

To accurately track and log end-user (retail player) activity in your Peabody Dashboard, it is required to provide a unique User ID and Email during every verification call. This allows you to audit specific users and detect multi-accounting or high-risk repeat offenders.

• External ID: Your internal database ID for the user (e.g., Player UUID or Username).
• External Email: The end-user's registered email address.

// Swift (iOS) Example
Peabody.verifyLocation(externalId: "user_123", externalEmail: "player@example.com") { result in
    // Handle result
}

Running Verification

To perform a check, call verifyLocation. This method automatically gathers GPS coordinates, IP intelligence, and device hardware signals. The response provides deep programmatic access to specific risk vectors.

// Swift (iOS)
Peabody.verifyLocation(
    externalId: "player_uuid_99",
    externalEmail: "player@domain.com"
) { result in
    switch result {
    case .success(let verdict):
        // 1. Direct Verdict
        if verdict.isCompliant {
            print("Access Granted. Risk Score: \(verdict.score)")
        }

        // 2. Programmatic Integrity Flags
        if verdict.isVPNOrProxyActive {
            print("Threat: VPN or Proxy Detected")
        }
        if verdict.isScreenCaptured {
            print("Threat: Screen Mirroring Active")
        }

        // 3. Location Metadata
        print("Device City: \(verdict.city)")
        print("IP Address: \(verdict.ipAddress)")
        
    case .failure(let error):
        print("Verification error: \(error.localizedDescription)")
    }
}

Continuous Jurisdictional Monitoring

For applications requiring constant compliance (such as live betting or regulated gaming), Peabody supports a "Heartbeat" mode. This automatically re-verifies the user's location at a set interval while the app is active, handling app lifecycle events (foreground/background) efficiently.

// Start monitoring every 15 minutes (900 seconds)
                Peabody.startMonitoring(
                interval: 900,
                externalId: "user_123",
                externalEmail: "player@example.com"
                ) { result in
                switch result {
                case .success(let verdict):
                if !verdict.isCompliant {
                // Take action: e.g. pause the game session
                print("Jurisdictional change detected: \(verdict.reason)")
                }
                case .failure(let error):
                print("Monitoring error: \(error.localizedDescription)")
                }
                }

Hardware-Backed Integrity

The Peabody SDK utilizes Apple's App Attest service to prove that requests originate from a genuine, unmodified device. This is handled automatically during the verifyLocation flow.

• Cryptographic proof via Secure Enclave
• Automatic key rotation and registration
• Replay protection via stateless HMAC challenges

Advanced Network Security (SSL Pinning)

To prevent Man-in-the-Middle (MITM) attacks and credential intercept, the Peabody iOS SDK employs Public Key Pinning. Every connection to our compliance servers is validated against known, trusted keys. If a mismatch is detected, the SDK immediately terminates the connection and logs a security event to your dashboard.

Android SDK

Integrate sub-second location integrity and Google Play Integrity verification into your Android applications.

Installation

The Peabody SDK for Android is distributed via Maven. To integrate it, add the dependency to your app-level build.gradle file and ensure your repository settings are configured.

Step 1: Add Dependency

// build.gradle
dependencies {
    implementation 'com.peabodycompliance:sdk-android:1.1.0'
}

Step 2: Repository Configuration

Ensure mavenCentral() is included in your settings.gradle or project-level build.gradle. If you are using a private repository, add the following:

// settings.gradle
dependencyResolutionManagement {
    repositories {
        mavenCentral()
        // Add custom repository if provided
    }
}

Configuration

Initialize the SDK early in your application lifecycle, typically in your MainActivity or Application class. Choose the method that matches your security architecture.

Method 1: Client ID Handshake (Recommended) — SDK 1.0.5+

Use this method to keep your API key off the device entirely. The SDK automatically calls your backend handshake endpoint to exchange the clientId for a short-lived sessionToken. Your backend proxies the request to Peabody's handshake.php. The SDK then calls verify.php directly with that token — your API key never touches the device.

Both URLs default to Peabody's own endpoints. Supply handshakeUrl and/or verifyUrl to route traffic through your own backend instead.

// Kotlin (SDK 1.0.6+) — route both calls through your backend
Peabody.configureWithClientId(
    context = this,
    clientId = "your_client_id_here",
    cloudProjectNumber = 350256575822L,
    handshakeUrl = "https://your-backend.com/peabody-handshake",  // optional
    verifyUrl    = "https://your-backend.com/peabody-verify"       // optional
)

// Omit both URLs to use Peabody's default endpoints directly
Peabody.configureWithClientId(
    context = this,
    clientId = "your_client_id_here",
    cloudProjectNumber = 350256575822L
)

// Legacy alias — serverURL is still accepted (same as handshakeUrl)
// Peabody.configureWithClientId(..., serverURL = "https://your-backend.com/peabody-handshake")

Integration Flow

Minimal backend proxy (Node / Express)

// POST /peabody-handshake
app.post('/peabody-handshake', async (req, res) => {
  const { clientId, externalId, externalEmail } = req.body;
  const response = await fetch('https://www.peabodycompliance.com/handshake.php', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientId, externalId, externalEmail })
  });
  const data = await response.json(); // { sessionToken, expiresIn }
  res.json(data);
});

Method 2: Direct API Key

Use only for server-to-server integrations or internal tooling where the API key never leaves your infrastructure. Do not embed your API key in a distributed APK.

// Kotlin
Peabody.configureWithApiKey(
    context = this,
    apiKey = "your_api_key_here",
    cloudProjectNumber = 350256575822L
)

Proxy Integrity Guarantee (SDK v1.1.0)

Operators using the Client ID Handshake method may configure a custom verifyUrl to route verification requests through their own backend before they reach Peabody. This is a legitimate and common pattern — it gives operators control over rate limiting, logging, and additional business logic.

However, it raises an important question: what prevents an operator from altering the GPS coordinates in transit to make a user in a restricted location appear compliant?

SDK v1.1.0 closes this gap with nonce binding — a cryptographic chain that ties the device-measured location data to the Google Play Integrity token in a way that cannot be forged or altered without detection.

How Nonce Binding Works

Tampered Response Example

When a nonce mismatch is detected, the response and audit log look like this:

// verify.php response when tampering is detected:
{
  "status":     "failure",
  "compliant":  false,
  "risk_score": "100",
  "risk_level": "Critical",
  "reason":     "Data Integrity Mismatch - Tampering Detected"
}

// Server-side audit log entry (error_log):
// Peabody Security CRITICAL: Android Nonce Mismatch - Tampering Detected.
// UserID=4821 Key=a3f8c2d1... IP=203.0.113.47 BundleID=com.operator.app
// Expected=e3b0c44298fc... Got=a665a45920422...

Running Verification

Verify a user's location and device integrity by calling verifyLocation. The SDK automatically acquires a fresh high-accuracy GPS fix, performs reverse geocoding, and submits a Play Integrity token.

// Kotlin
Peabody.verifyLocation(
    externalId = "user_abc_123",
    externalEmail = "player@email.com"
) { result ->
    result.onSuccess { verdict ->
        if (verdict.isCompliant) {
            // Access Granted
            Log.d("Peabody", "Verified: ${verdict.score}/100")
        }
    }.onFailure { error ->
        // Handle network or permission errors
    }
}

Verification Response — Location Metadata

Every verify.php response includes a metadata object with the reverse-geocoded location. For users inside the US, the jurisdiction.code field (e.g. US-NV) is the primary signal. For international users, use metadata.country and metadata.state to apply regional policy on your backend.

{
  "compliant": true,
  "jurisdiction": {
    "code": "UNKNOWN",
    "resolved": false,
    "operator_note": "Location outside loaded jurisdiction boundaries. Operator should apply jurisdiction policy."
  },
  "metadata": {
    "lat": 31.2304,
    "lon": 121.4737,
    "city": "Shanghai",
    "state": "Shanghai",
    "country": "China"
  }
}

Peabody Verify on Google Play

For Android users accessing your platform through a mobile web browser (rather than your native app), Peabody Verify is available on the Google Play Store. The JS SDK automatically fires a Chrome Intent URL when it detects an Android browser — if the app is installed it opens directly; if not, Chrome redirects to the Play Store automatically.

Play Console Linking

For hardware-backed integrity to function, your app must be linked to a Google Cloud project with the Play Integrity API enabled, and those credentials must be configured in your Peabody dashboard. Each operator uses their own Google Cloud project — this keeps your app fully isolated and requires no access to Peabody's infrastructure.

Once saved, Peabody uses your credentials to verify Play Integrity tokens for your app. Your service account JSON is stored encrypted and is never returned to the browser or exposed in API responses.

JavaScript SDK (Web)

Secure your web applications and sweepstakes sites using our browser-based trust layer.

Installation

You can integrate the Peabody Web SDK using our hosted CDN for immediate updates, or download the source for self-hosting.

Option 1: CDN (Recommended)

Include the Peabody script directly in your HTML <head>. This ensures you always have the latest security definitions.

<script src="https://peabodycompliance.com/resources/js/peabody.min.js"></script>

Option 2: Self-Hosting

For organizations requiring full control over assets, you can download the script and host it on your own servers. Contact support for access to the self-hosted distribution package.

Configuration & Authentication

The JS SDK authenticates via a session token — a short-lived credential issued by Peabody's handshake endpoint. The flow is always the same: your backend calls Peabody's /handshake.php using your Client ID (found in your dashboard), receives a session token, and passes it to the browser. The browser then calls /verify.php with that token — which is how Peabody identifies your account and bills one credit per call.

The Handshake Call (with Binding)

When calling /handshake.php, provide the externalId and externalEmail of the user you are about to verify. This locks the token to that specific user.

POST https://peabodycompliance.com/handshake.php
Content-Type: application/json

{
  "clientId":  "your_client_id",
  "bundleId":  "your-domain.com",
  "platform":  "web",
  "externalId": "user_12345",
  "externalEmail": "player@email.com"
}

// Peabody responds:
{
  "sessionToken": "a3f8c2d1e4f6...",
  "expiresIn": 7200
}

There are two integration patterns depending on your stack:

Pattern 1 — Server-Side Rendering (SSR)

Your backend calls the Peabody handshake on every protected page load and injects the returned token directly into the HTML. The token is baked in before the browser sees it — no extra client-side round trip needed.

PHP

<?php
// Your backend calls Peabody's handshake to get a session token
// We pass the user's ID and Email to BIND the token to this specific user.
$response = file_get_contents('https://www.peabodycompliance.com/handshake.php', false,
    stream_context_create(['http' => [
        'method'  => 'POST',
        'header'  => 'Content-Type: application/json',
        'content' => json_encode([
            'clientId'      => 'your_client_id',
            'bundleId'      => 'your-domain.com',
            'platform'      => 'web',
            'externalId'    => $user->id,
            'externalEmail' => $user->email
        ])
    ]])
);
$peabody = json_decode($response, true);
$sessionToken = $peabody['sessionToken'];
?>
<script src="https://www.peabodycompliance.com/resources/js/peabody.min.js"></script>
<script>
  Peabody.config.sessionToken         = '<?= htmlspecialchars($sessionToken, ENT_QUOTES) ?>';
  Peabody.config.tokenRefreshEndpoint = '/your-token-refresh-endpoint';
</script>

Node / Express

const fetch = require('node-fetch');

app.get('/protected-page', requireAuth, async (req, res) => {
  // Call Peabody handshake server-side
  const peabody = await fetch('https://peabodycompliance.com/handshake.php', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: 'your_client_id',
      bundleId: 'your-domain.com',
      platform: 'web'
    })
  }).then(r => r.json());

  // Inject the token into your rendered template
  res.render('protected-page', { sessionToken: peabody.sessionToken });
});

// In your template (EJS, Handlebars, etc.):
// <script>
//   Peabody.config.sessionToken         = '<%= sessionToken %>';
//   Peabody.config.tokenRefreshEndpoint = '/your-token-refresh-endpoint';
// </script>

Python / Flask

import requests
from flask import render_template
from functools import wraps

@app.route('/protected-page')
@login_required
def protected_page():
    # Call Peabody handshake server-side
    peabody = requests.post('https://peabodycompliance.com/handshake.php', json={
        'clientId': 'your_client_id',
        'bundleId': 'your-domain.com',
        'platform': 'web'
    }).json()

    return render_template('protected_page.html',
                           session_token=peabody['sessionToken'])

# In your Jinja2 template:
# <script>
#   Peabody.config.sessionToken         = '{{ session_token }}';
#   Peabody.config.tokenRefreshEndpoint = '/your-token-refresh-endpoint';
# </script>

Pattern 2 — Single-Page Apps (SPA / React / Vue / Angular)

For client-side SPAs there is no server-rendered page to inject into. Instead, create a small protected endpoint on your own backend that calls the Peabody handshake and returns the token to your frontend. Point tokenRefreshEndpoint at that same route so the SDK can renew automatically.

Your backend token endpoint (any language)

// Example: Express route — requires the user to be authenticated first
app.post('/api/peabody-token', requireAuth, async (req, res) => {
  // Call Peabody handshake with your Client ID (server-side only)
  const peabody = await fetch('https://peabodycompliance.com/handshake.php', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientId: 'your_client_id',  // ← kept on your server, never sent to browser
      bundleId: 'your-domain.com',
      platform: 'web'
    })
  }).then(r => r.json());

  res.json({ sessionToken: peabody.sessionToken });
});

Frontend (JavaScript / React / Vue)

// On app load, fetch a token from your own backend (user must be logged in)
async function initPeabody() {
  const res  = await fetch('/api/peabody-token', { credentials: 'include' });
  const data = await res.json();

  Peabody.config.sessionToken         = data.sessionToken;
  Peabody.config.tokenRefreshEndpoint = '/api/peabody-token'; // SDK auto-refreshes here on expiry
}

await initPeabody();

Automatic Token Refresh

When a token expires, the SDK automatically calls your tokenRefreshEndpoint, which in turn calls the Peabody handshake to issue a fresh token. The failed verification is then retried transparently — no action needed from your application code.

// Your refresh endpoint calls Peabody's handshake (same as above)
// The SDK calls it automatically when it gets a 401 — then retries the verification.
Peabody.config.tokenRefreshEndpoint = '/api/peabody-token';

// That's it. The SDK handles the rest silently.

Web Verification

Trigger a verification session when a user performs a high-value action. On desktop this gathers browser telemetry and hardware agent data. On iPhone/iPad it automatically fires the Peabody Verify deep link, and on Android it fires the Peabody Verify Intent URL — no extra configuration required for either mobile platform.

async function checkUser() {
  const result = await Peabody.verifySession('user_123', 'player@email.com');

  // Case 1: Browser Restriction (Safari macOS)
  if (result.status === 'browser_unsupported') {
    showBrowserSwitchPrompt(); // Advise user to use Chrome or Firefox
    return;
  }

  // Case 2: iOS/iPadOS — app not installed
  if (result.status === 'app_required') {
    showAppStorePrompt();
    return;
  }

  // Case 3: Desktop — agent required but not running
  if (result.status === 'download_required') {
    showAgentInstallModal(result.downloadUrl);
    return;
  }

  // Handle errors or success...
}

Heartbeat & 15-Minute Re-Verification

For regulated operators (sports betting, iGaming, live content) requiring continuous compliance, Peabody provides a server-driven heartbeat. verify.php records a last_verified_at timestamp in the session on every successful iOS verification. The JS SDK polls check_session.php every 60 seconds and automatically re-triggers the iOS app when the 15-minute window expires.

Heartbeat API

// Call after the iOS app completes initial verification and the user returns to the browser.
// Default interval is 60,000 ms (60 seconds).
Peabody.startHeartbeat();

// Stop the heartbeat on logout or page unload.
Peabody.stopHeartbeat();

// Single poll — check the server-side session status once.
// Useful for confirming the iOS app has posted back before granting access.
const status = await Peabody.checkSession();
// { status: "valid",   age_seconds: 247, expires_in_seconds: 653 }
// { status: "expired", reason: "re-verification required" }

Configuration

// Default — points to Peabody's hosted endpoint. No change needed for most integrations.
Peabody.config.heartbeatEndpoint = 'https://www.peabodycompliance.com/check_session.php';

// Override the poll interval (milliseconds):
Peabody.startHeartbeat(30000);  // poll every 30 seconds

What Happens on Expiry

When check_session.php returns status: "expired", the SDK automatically:

1. Clears the client-side sessionStorage verification cache.
2. Shows a full-screen "Verifying Location..." overlay — blocking the UI while re-verification is in progress.
3. Re-fires the peabodyverify:// deep link so the iOS app performs a fresh location check.
4. Hides the overlay automatically once the next heartbeat poll returns status: "valid".

check_session.php Reference

POST https://peabodycompliance.com/check_session.php
Content-Type: application/json

{ "sessionToken": "your_session_token" }

// Valid — last verified less than 15 minutes ago:
{ "status": "valid", "age_seconds": 247, "expires_in_seconds": 653 }

// Expired — 15+ minutes since last verification:
{ "status": "expired", "reason": "re-verification required", "age_seconds": 1043 }

// Invalid or expired session token:
HTTP 401 → { "status": "error", "message": "Invalid or expired session" }

Desktop Compliance Agents (Mac & Windows)

Hardware-backed location verification for macOS and Windows desktop users — bridging the gap between browser GPS and physical truth.

How It Works

The agent is a lightweight system service (PeabodyService) that runs a local HTTP server on localhost:12180. When the Peabody JS SDK detects a desktop environment, it silently probes this port. If the agent is running, its hardware payload is included in the verification POST to your server. Your server then verifies the signature and uses the WiFi triangulation data — via the Google Geolocation API — to resolve the user's true physical coordinates.

SDK Configuration

Options are available in Peabody.config to control agent behavior for Mac, Windows, and Linux:

Peabody.config.sessionToken       = 'your_session_token';

// Set true to REQUIRE the agent on desktop browsers (Mac, Windows, Linux).
// If the agent is not running, verifySession() returns { status: 'download_required' }
// instead of falling back to browser GPS.
Peabody.config.requireDesktopAgent = true;

// Download page URLs — users are redirected here when the agent is not installed.
Peabody.config.macAgentDownloadUrl     = 'https://www.peabodycompliance.com/downloads/PeabodyService.dmg';
Peabody.config.windowsAgentDownloadUrl = 'https://www.peabodycompliance.com/downloads/windows.html';
Peabody.config.linuxAgentDownloadUrl   = 'https://www.peabodycompliance.com/downloads/linux.html';

When requireDesktopAgent is false (the default), the agent is used opportunistically — if it's running, its data enhances the verification; if not, standard browser geolocation is used as a fallback. Set it to true only when you need the highest-assurance mode on desktop.

Linux & Steam Deck Agent Beta

Hardware-backed location and device verification for Linux desktops and Steam Deck — the first geolocation compliance agent for the Linux platform.

Distributing the Agent

The agent binary is hosted at:

The SDK's default linuxAgentDownloadUrl points to the download page at /downloads/linux.html, which walks users through installation. No additional configuration is required for most integrations.

User Installation Steps

The agent is a one-time install. Once running, all future verifications happen silently in the background.

1. Download PeabodyAgent-linux-amd64 from the link above.
2. Open a terminal and make the file executable: chmod +x PeabodyAgent-linux-amd64
3. Run the installer: ./PeabodyAgent-linux-amd64 --install
4. Return to the site and refresh — verification completes automatically.

Server-Side Verification

When linux_hardware is present in the payload, verify.php applies the following logic:

• VPN detection from /proc/net/dev (tun, tap, WireGuard, ProtonVPN, NordLynx, Mullvad, PIA) overrides browser WebRTC signals.
• Wi-Fi BSSIDs from nmcli are sent to the Google Geolocation API for triangulation. If nmcli is unavailable, browser GPS is used as fallback.
• Virtual machine environments (VirtualBox, VMware, KVM, HyperV, Xen) are detected via DMI and CPU flags — VM sessions receive a risk score of 100 and are rejected.
• Wine compatibility layer is detected and scored +70 risk.
• Steam Deck hardware is identified natively (Jupiter/Galileo DMI product names) — Steam Deck is treated as real hardware, not a VM.
• device_id is derived from /etc/machine-id for cross-session device tracking.
• Low-precision and IP distance penalties are suppressed — same as Mac and Windows agents.

Agent Payload Schema

The raw JSON returned by http://localhost:12180 and forwarded under linux_hardware:

{
  "agentVersion": "1.0.0",
  "platform": "linux",
  "device": {
    "machineId":   "a1b2c3d4e5f6...",   // /etc/machine-id
    "hostname":    "my-ubuntu-pc",
    "osRelease":   "Ubuntu 24.04.2 LTS",
    "isVM":        false,
    "vmType":      "",
    "isSteamDeck": false,
    "isWine":      false
  },
  "vpn": {
    "vpnDetected":   false,
    "vpnInterfaces": null                 // e.g. ["tun0", "wg0"] when VPN active
  },
  "wifi": {
    "accessPoints": [
      { "macAddress": "aa:bb:cc:dd:ee:ff", "signalStrength": -58, "channel": 6 },
      { "macAddress": "11:22:33:44:55:66", "signalStrength": -71, "channel": 11 }
    ],
    "scanError": ""                       // set if nmcli unavailable
  }
}

Peabody Verify (iOS)

High-integrity location and device verification for users on mobile browsers and tablets — where the Peabody desktop agents cannot run and the native iOS SDK is not embedded in the operator's app.

How It Works

When Peabody.verifySession() is called on an iPhone or iPad, the JS SDK automatically fires the Peabody Verify deep link — no additional configuration required. No browser-side GPS or WebRTC telemetry is attempted; the iOS app is the sole source of truth.

Deep Link URL Format

The SDK constructs the deep link automatically from Peabody.config.sessionToken and the current page URL. The iOS app must parse both parameters from the incoming URL.

peabodyverify://verify?session=SESSION_TOKEN&returnUrl=https%3A%2F%2Fyoursite.com%2Fgame

iOS App Requirements (Swift)

The Peabody Verify iOS app must handle two things to complete the integration:

// 1. Parse the session token and returnUrl from the incoming deep link
//    in your AppDelegate / Scene delegate:
func scene(_ scene: UIScene, openURLContexts contexts: Set<UIOpenURLContext>) {
    guard let url = contexts.first?.url,
          let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
          let sessionParam = components.queryItems?.first(where: { $0.name == "session" })?.value,
          let returnParam  = components.queryItems?.first(where: { $0.name == "returnUrl" })?.value,
          let returnUrl    = URL(string: returnParam) else { return }

    VerificationService.shared.verify(sessionToken: sessionParam) { success in
        guard success else { return }

        // 2. Redirect back to the browser after successful verification.
        //    Validate the domain against your allowlist first.
        let allowedHosts = ["yoursite.com", "app.yoursite.com"]
        if allowedHosts.contains(returnUrl.host ?? "") {
            UIApplication.shared.open(returnUrl)
        }
    }
}

Continuous Compliance — 15-Minute Heartbeat

After the iOS app redirects the user back to the browser, poll Peabody.checkSession() to confirm verification completed, then call Peabody.startHeartbeat() to begin the 60-second compliance loop. When the 15-minute window expires, the SDK automatically shows an overlay and re-triggers the deep link.

// On page load (after the user returns from the Peabody Verify app):
async function waitForVerificationThenStart() {
    // Poll up to 10 seconds to confirm the iOS app posted to verify.php
    for (let i = 0; i < 10; i++) {
        const status = await Peabody.checkSession();
        if (status.status === 'valid') {
            Peabody.startHeartbeat();   // begin 60-second server-side polling
            enableGameplay();           // grant access to regulated content
            return;
        }
        await new Promise(r => setTimeout(r, 1000));
    }
    // App did not complete in time — re-trigger
    Peabody.verifySession('user_123', 'player@email.com');
}

waitForVerificationThenStart();

// On logout or page unload:
window.addEventListener('beforeunload', () => Peabody.stopHeartbeat());

Handling the download_required and app_required Responses

When the required component is not detected, verifySession() returns a special status without calling your server. Handle each case in your UI:

const result = await Peabody.verifySession('user_123', 'player@email.com');

// iOS/iPadOS — Peabody Verify app not installed
if (result.status === 'app_required' && /iPhone|iPad|iPod/.test(navigator.userAgent)) {
    showAppStoreLink('https://apps.apple.com/us/app/peabody-verify/id6762066589');
    return;
}

// Android — Peabody Verify app not installed (non-Chrome browser fallback)
if (result.status === 'app_required' && /Android/.test(navigator.userAgent)) {
    showPlayStoreLink('https://play.google.com/store/apps/details?id=com.peabodycompliance.verify');
    return;
}

// Desktop (Mac, Windows, or Linux) — compliance agent not running
if (result.status === 'download_required') {
    showAgentInstallModal(result.downloadUrl);  // result.downloadUrl points to DMG, EXE, or linux.html
    return;
}

// All other statuses proceed normally
if (result.compliant) { /* access granted */ }

Distributing the Agent

No build step required. Peabody hosts a signed and Apple-notarized DMG on our servers. The SDK's default macAgentDownloadUrl already points to it — so if you use the CDN-hosted SDK, your users will automatically receive our verified installer with no configuration needed.

This is the default value of Peabody.config.macAgentDownloadUrl. You can override it if you need to self-host the DMG on your own infrastructure, but for most integrations no change is needed:

// Default — uses Peabody's hosted, signed DMG. No action required.
Peabody.config.macAgentDownloadUrl = 'https://www.peabodycompliance.com/downloads/PeabodyService.dmg';

// Override only if self-hosting on your own servers:
// Peabody.config.macAgentDownloadUrl = 'https://your-domain.com/downloads/PeabodyService.dmg';

User Installation Steps

The agent is a one-time install. Once it is running, all future verifications happen silently in the background — the user will never see the install prompt again.

1. The DMG downloads automatically. Open it from the Downloads folder.
2. Drag PeabodyServiceMac into the Applications folder shown in the installer window.
3. Open PeabodyServiceMac from Applications. Grant Location Services and Network access when prompted by macOS.
4. A small icon appears in the macOS menu bar — the agent is now running. Return to the page to continue.

Server-Side Verification (verify.php)

When a Mac hardware payload is present, your server must verify the ECDSA P-256 signature before trusting any of the hardware signals. The Peabody verify.php reference implementation handles this automatically. Key behaviors when mac_hardware is present in the payload:

• ECDSA signature is verified against the included public key (DER/SPKI format). Request is rejected with HTTP 403 if verification fails.
• Top 5 nearby networks by RSSI strength are sent to the Google Geolocation API. The returned coordinates replace browser GPS as the authoritative location.
• vpn_active from the OS routing table overrides browser WebRTC VPN detection.
• device_id (hardware UUID) is stored in the log, enabling cross-session device tracking and multi-accounting detection.
• The connected access point BSSID is stored in verification_logs.bssid.
• Low-precision and IP distance discrepancy risk penalties are suppressed — desktop Macs have no GPS chip, so browser accuracy is inherently coarse, and ISP routing makes IP geolocation unreliable.

Agent Payload Schema

The raw JSON returned by http://localhost:12180 and forwarded to your server under mac_hardware:

{
  "timestamp": 1711046400,
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "connected_network": {
    "ssid": "MyWiFiNetwork",
    "bssid": "aa:bb:cc:dd:ee:ff",
    "rssi": -42
  },
  "nearby_networks": [
    { "ssid": "MyWiFiNetwork",   "bssid": "aa:bb:cc:dd:ee:ff", "rssi": -42 },
    { "ssid": "NeighborNet",     "bssid": "11:22:33:44:55:66", "rssi": -71 }
  ],
  "vpn_active": false,
  "signature": "MEUCIQDa...",   // ECDSA P-256 signature over sorted JSON
  "public_key": "MFkwEwYH..."   // DER/SPKI-encoded EC public key (base64)
}

SDK Response Structure

The verification call returns a comprehensive object containing all trust signals. Whether using the iOS or JavaScript SDK, the underlying data structure is consistent.

{
  "status": "failure",
  "compliant": false,
  "risk_score": "100",
  "risk_level": "Critical",
  "reason": "Located in exclusion zone: Atlantic City Casino District; Proxy/VPN detected",
  "external_id": "user_12345",
  "device_integrity": {
    "hardware_integrity": true,
    "is_jailbroken": false,
    "is_mock_location": false,
    "is_screen_captured": false,
    "is_vpn_active": true
  },
  "jurisdiction": {
    "name": "New Jersey",
    "code": "US-NJ",
    "status": "active",
    "resolved": true,
    "in_us": true
  },
  "exclusion_zone": {
    "active": true,
    "name": "Atlantic City Casino District",
    "type": "casino_floor"
  },
  // Tribal zone example — same structure:
  // "exclusion_zone": { "active": true, "name": "Ho-Chunk Nation", "type": "exclusion" }
  "metadata": {
    "lat": 39.3585,
    "lon": -74.4358,
    "ip": "149.102.244.98",
    "city": "Atlantic City",
    "state": "NJ",
    "country": "United States"
  },
  "timestamp": "2026-03-08 15:03:50"
}