PLD Tracker

A WordPress plugin for synchronizing browser identity tokens across multiple WordPress websites.

Cross-Site Identity Sync allows participating WordPress sites to share a browser identity token through secure server-to-server REST API synchronization. The plugin uses a configurable browser identifier, temporary server-side storage, signed requests, optional HTTP Basic Authentication, and analytics-consent-aware cookies.

Features

• 🔗 Cross-domain identity synchronization
• 🌐 Support for multiple participating WordPress sites
• 🔐 HMAC-SHA256 signed server-to-server synchronization
• 🍪 Consent-aware tracking cookies
• 🛡️ Analytics consent validation
• 🔑 Configurable shared secret
• 🔒 Optional HTTP Basic Authentication
• ⏱️ Configurable token TTL
• 📡 WordPress REST API endpoints
• 🧩 Temporary token storage using WordPress transients
• 🚫 Origin validation for browser requests
• ✅ Browser fingerprint/token validation
• 📋 Configurable allowed-site list
• ⚙️ WordPress Admin settings
• 🔄 Automatic push to other configured sites
• 🐞 Optional debug response information
• 📦 Lightweight implementation using native WordPress APIs

How It Works

The plugin uses a browser identifier (fid) and tracking token to establish a shared identity across participating websites.

The general flow is:

Browser
   │
   │ Fingerprint / Browser ID + Token
   ▼
Site A
   │
   │ /capture
   ▼
Temporary Token Storage
   │
   │ Signed Server-to-Server Request
   ├──────────────────────► Site B
   │                         │
   │                         ▼
   │                    /sync endpoint
   │                         │
   │                         ▼
   │                    Temporary Storage
   │
   ▼
Browser requests /apply
   │
   ▼
Tracking Cookie

When a token is captured on one participating site, the plugin can push that token to the other configured sites.

The receiving site verifies the signed request, validates the source site and timestamp, and temporarily stores the token.

When the browser subsequently requests the /apply endpoint, the pending token can be written to the configured tracking cookie.

Core Concepts

Browser ID

The plugin uses a browser identifier called:

fid

The identifier is validated against the following pattern:

[A-Za-z0-9_-]{8,128}

This identifier is used as the key for temporary token storage.

Tracking Token

The plugin accepts a token associated with the browser identity.

Tokens are validated against:

[A-Za-z0-9_.@:-]{1,255}

Tracking Cookie

The cookie name is configurable from WordPress Admin.

The default cookie name is:

special_cookie

You can change this to the cookie name required by your implementation.

REST API

The plugin registers three REST API endpoints under:

/wp-json/csft/v1/

Capture

POST /wp-json/csft/v1/capture

The capture endpoint receives a browser identifier and token.

Example:

{
  "fid": "abc123456789",
  "token": "browser-token-value"
}

The plugin validates both values before storing the token.

After storing the token locally, the plugin can push the token to other configured participating sites.

Capture Flow

The capture request performs the following operations:

1. Validate the browser identifier.
2. Validate the token.
3. Store the token temporarily.
4. Load the configured participating sites.
5. Exclude the current site.
6. Generate a signed request for each destination.
7. Send the request to the destination site's /sync endpoint.
8. Return a success response.

The implementation uses WordPress wp_remote_post() for server-to-server communication.

Sync

POST /wp-json/csft/v1/sync

The sync endpoint receives token information from another participating WordPress site.

Example request body:

{
  "fid": "abc123456789",
  "token": "browser-token-value",
  "source": "https://site-a.example.com",
  "timestamp": 1750000000
}

Before accepting the request, the plugin verifies:

• HMAC signature
• Browser identifier
• Token
• Timestamp
• Source URL
• Allowed-site configuration

If validation succeeds, the token is stored temporarily.

Request Signing

Cross-site synchronization uses an HMAC-SHA256 signature.

The signature is generated using:

request body + "|" + destination host

and the configured shared secret.

Conceptually:

HMAC-SHA256(
    request_body + "|" + destination_host,
    shared_secret
)

The generated signature is sent through:

X-CSFT-Signature

The receiving site independently calculates the expected signature and compares it using hash_equals().

This prevents unauthenticated sites from submitting arbitrary synchronization requests.

Shared Secret

Every participating site must use the same shared secret for synchronization.

Example:

Site A
Shared Secret: ********

Site B
Shared Secret: ********

Site C
Shared Secret: ********

The shared secret is required for server-to-server synchronization.

Do not commit the shared secret to Git.

Timestamp Validation

Synchronization requests contain a timestamp.

The plugin rejects requests that fall outside the configured token TTL window.

The timestamp must satisfy:

timestamp >= current_time - TTL

and:

timestamp <= current_time + 60 seconds

This helps reduce the risk of replaying old synchronization requests.

Apply

POST /wp-json/csft/v1/apply

The apply endpoint checks whether a token is pending for the supplied browser identifier.

If a valid pending token exists and analytics consent permits tracking, the plugin writes the token to the configured tracking cookie.

Example:

{
  "fid": "abc123456789"
}

Successful application returns:

{
  "success": true,
  "applied": true
}

If no token is pending:

{
  "success": true,
  "applied": false
}

Token Storage

Pending tokens are stored using WordPress transients.

The transient key follows this structure:

csft_{fid}

The stored data contains:

[
    'token' => '...',
    'time'  => time()
]

The lifetime of the transient is controlled by the configured token TTL.

Token TTL

The default token TTL is:

300 seconds

which equals:

5 minutes

The value can be changed from the plugin settings.

Example:

Token TTL: 300

The TTL controls how long pending synchronization data remains valid.

Analytics Consent

The plugin is designed to avoid writing the tracking cookie when analytics consent has not been granted.

Before setting the tracking cookie, the plugin checks configured consent cookies.

The consent system supports two types of cookies:

Direct Consent Cookies

These contain a direct value such as:

yes

The plugin can be configured with one or more direct consent cookie names.

Default:

cookielawinfo-checkbox-analytics

Structured Consent Cookies

The plugin also supports consent cookies containing comma-separated key/value pairs.

Example:

necessary:yes,analytics:yes,advertisement:no

The plugin extracts the configured analytics key.

Default:

analytics

The expected allowed value defaults to:

yes

Consent Behavior

When analytics consent is not granted:

Tracking cookie
      │
      ▼
Cleared

When analytics consent is granted:

Pending token
      │
      ▼
Tracking cookie
      │
      ▼
30-day expiration

The plugin clears the configured tracking cookie when analytics consent is not allowed.

Tracking Cookie

The tracking cookie is created with:

Path: /

The cookie expiration is:

30 days

For HTTPS sites, the cookie uses:

Secure: true
SameSite: None

For non-HTTPS environments, the implementation uses:

Secure: false
SameSite: Lax

The cookie is intentionally not marked HttpOnly because it is designed to be available to browser-side tracking functionality.

Allowed Sites

Participating domains are configured through the Allowed Sites setting.

Example:

https://site-a.example.com
https://site-b.example.com
https://site-c.example.com

One URL can be entered per line.

The plugin normalizes configured URLs before processing them.

Cross-Site Push

When a token is captured on one site, the plugin determines the configured participating sites.

The current site is excluded from the push list.

For each remaining site, the plugin sends:

POST /wp-json/csft/v1/sync

with:

Content-Type: application/json
X-CSFT-Signature: <signature>

If HTTP Basic Authentication is configured, the request can also include:

Authorization: Basic <credentials>

HTTP Basic Authentication

The plugin supports optional HTTP Basic Authentication for destination sites.

This is useful when non-production environments are protected by HTTP authentication.

Configure:

HTTP Auth Username
HTTP Auth Password

The credentials are automatically converted into an Authorization header.

Example:

Authorization: Basic base64(username:password)

Browser Origin Validation

Browser-facing endpoints use origin validation.

The plugin reads:

HTTP_ORIGIN

and, when necessary, falls back to:

HTTP_REFERER

The origin is normalized and compared against the current WordPress site's origin.

This prevents browser-side requests from arbitrary origins from accessing the capture and apply endpoints.

Security

The plugin includes multiple security mechanisms:

HMAC Authentication

Server-to-server synchronization requires a valid HMAC-SHA256 signature.

Shared Secret

A shared secret is required to generate and validate synchronization signatures.

Timestamp Validation

Requests outside the allowed TTL window are rejected.

Allowed Source Validation

The synchronization source must be present in the configured allowed-site list.

Origin Validation

Browser-facing requests must originate from the current site's origin.

Input Validation

Browser IDs and tokens are validated against strict character and length requirements.

Capability Protection

Plugin configuration is exposed through the WordPress Settings API and the settings page requires:

manage_options

WordPress Nonces / Settings API

Configuration is registered using the WordPress Settings API.

Admin Settings

The plugin adds a settings page under:

WordPress Admin
→ Settings
→ CS Fingerprint

The current admin UI label is CS Fingerprint, while the recommended repository/plugin branding is Cross-Site Identity Sync.

The settings page contains:

Setting	Description
Cookie Name	Name of the tracking cookie
Token TTL	Lifetime of pending synchronization data
Shared Secret	HMAC secret shared by participating sites
HTTP Auth Username	Optional Basic Auth username
HTTP Auth Password	Optional Basic Auth password
Allowed Sites	Participating site URLs
Direct Consent Cookie Names	Cookies containing direct analytics consent
Structured Consent Cookie Names	Cookies containing structured consent data
Analytics Consent Key	Key to read from structured consent cookies
Analytics Allowed Value	Value required before tracking is enabled

Configuration Example

Cookie Name:
special_cookie

Token TTL:
300

Shared Secret:
your-shared-secret

HTTP Auth Username:
username

HTTP Auth Password:
password

Allowed Sites:
https://site-a.example.com
https://site-b.example.com
https://site-c.example.com

Direct Consent Cookie Names:
cookielawinfo-checkbox-analytics

Structured Consent Cookie Names:
cookieyes-consent
cookieyes_consent

Analytics Consent Key:
analytics

Analytics Allowed Value:
yes

Frontend JavaScript

The plugin loads:

assets/js/csft.js

on the frontend.

The script receives configuration through:

CSFT_CONFIG

The localized configuration contains:

{
    capture_url: "...",
    apply_url: "...",
    cookie_name: "..."
}

The JavaScript file is loaded as an ES module.

Debug Mode

The Capture and Apply endpoints support an optional:

debug

parameter.

Example:

/wp-json/csft/v1/capture?debug=1

Debug responses can expose information such as:

• Browser ID
• Allowed sites
• Push results
• Pending token status
• Consent status
• Cookie name

Debug mode should only be used during development or troubleshooting.

Avoid exposing debug information publicly in production.

Installation

Method 1 — Upload Plugin ZIP

1. Create the plugin ZIP package.
2. Log in to WordPress Admin.
3. Go to:

Plugins → Add New → Upload Plugin

4. Upload the plugin ZIP.
5. Install the plugin.
6. Activate it.

Method 2 — Manual Installation

Copy the plugin directory into:

wp-content/plugins/

Expected structure:

cross-site-identity-sync/
├── cross-site-identity-sync.php
└── assets/
    └── js/
        └── csft.js

Activate the plugin from:

WordPress Admin → Plugins

Requirements

• WordPress
• PHP 7.4+
• HTTPS recommended for production
• WordPress REST API enabled
• Access to WordPress Transients
• Fingerprint/browser identity implementation on the frontend
• Configured participating domains
• Shared secret across participating sites

Example Multi-Site Architecture

                  ┌───────────────────┐
                  │     Site A        │
                  │ example.com       │
                  └─────────┬─────────┘
                            │
                            │ Capture
                            ▼
                    ┌───────────────┐
                    │ Identity Token│
                    └───────┬───────┘
                            │
              Signed Server-to-Server
                     Synchronization
                    ┌───────┴───────┐
                    │               │
                    ▼               ▼
          ┌────────────────┐ ┌────────────────┐
          │     Site B     │ │     Site C     │
          │ stage.example  │ │ qa.example     │
          └────────────────┘ └────────────────┘
                    │               │
                    └───────┬───────┘
                            │
                            ▼
                     Pending Token
                            │
                            ▼
                         /apply
                            │
                            ▼
                    Tracking Cookie

Typical Use Case

This plugin can be used when several related websites need to recognize the same browser identity without relying on a single shared browser cookie across unrelated domains.

For example:

Main Website
    │
    ├── Product Website
    │
    ├── Patient Website
    │
    └── Campaign Website

Each domain maintains its own cookie while the backend synchronizes the identity token between participating WordPress installations.

Plugin Architecture

The current implementation is intentionally lightweight and primarily contained in the main plugin file.

cross-site-identity-sync/
│
├── cross-site-identity-sync.php
│
└── assets/
    └── js/
        └── csft.js

Main PHP Components

The main plugin contains functions for:

• Settings retrieval
• Site URL normalization
• Site origin validation
• Browser request validation
• Fingerprint/token validation
• HMAC signing
• HMAC verification
• Consent parsing
• Tracking cookie management
• Temporary token storage
• REST API registration
• Admin settings
• Frontend script registration

REST API Endpoints Summary

Endpoint	Method	Purpose
/wp-json/csft/v1/capture	POST	Capture and distribute a browser token
/wp-json/csft/v1/sync	POST	Receive a token from another site
/wp-json/csft/v1/apply	POST	Apply a pending token to the tracking cookie

Data Flow Summary

Capture

Browser
→ Site A /capture
→ Validate fid/token
→ Store transient
→ Sign payload
→ Push to Site B/C

Sync

Site A
→ Signed /sync request
→ Site B
→ Verify signature
→ Validate source/timestamp
→ Store transient

Apply

Browser
→ Site B /apply
→ Find pending token
→ Check analytics consent
→ Set tracking cookie
→ Delete transient

Important Configuration Requirements

For cross-site synchronization to work correctly, every participating site should have:

1. The same shared secret.
2. The participating domains configured in Allowed Sites.
3. The correct REST API available.
4. Matching token/fingerprint implementation.
5. Correct analytics consent configuration.
6. Correct HTTP authentication configuration if required.
7. HTTPS enabled in production.

Production Security Recommendations

Before deploying this plugin to production:

• Use a strong randomly generated shared secret.
• Do not commit secrets to Git.
• Use HTTPS on every participating domain.
• Avoid enabling debug mode publicly.
• Use HTTP Basic Authentication only where required.
• Restrict WordPress administrator access.
• Review all participating domains.
• Remove unused domains from Allowed Sites.
• Ensure consent configuration matches your site's actual cookie-consent implementation.
• Review applicable privacy and cookie regulations for your deployment.

Important Privacy Note

This plugin is designed to synchronize browser identity tokens across participating domains.

Depending on how the browser identifier and token are generated and used, this functionality may constitute tracking or pseudonymous identification.

Before deploying it, ensure the implementation:

• Has an appropriate legal/privacy basis.
• Respects the site's consent requirements.
• Does not synchronize data beyond the intended purpose.
• Uses appropriate retention periods.
• Provides users with required privacy disclosures.
• Complies with applicable regulations and organizational policies.

The plugin itself does not provide legal compliance.

Troubleshooting

Token is not being applied

Check:

1. Browser ID is valid.
2. Token exists.
3. Token has not expired.
4. Analytics consent is granted.
5. Cookie name is configured correctly.
6. /apply endpoint is reachable.

Site-to-site synchronization fails

Check:

1. Shared secret matches on all sites.
2. Destination URL is present in Allowed Sites.
3. Destination REST API is accessible.
4. HMAC signature is being generated.
5. Destination site can receive POST requests.
6. HTTP Basic Auth credentials are correct if enabled.
7. Timestamp is within the configured TTL.

Browser request returns an error

Check:

1. HTTP Origin header.
2. HTTP Referer header.
3. Current site URL.
4. Allowed browser origin.
5. REST API availability.

Debugging

Temporarily append:

?debug=1

to the Capture or Apply request.

Review the returned debug information, then disable/remove debug usage before production deployment.

Current Version

Version: 1.0

Author

Shahid Ajmeri

License

Add the license appropriate for your project before publishing the repository publicly.

Changelog

1.0

• Initial PLD Tracker implementation
• Added browser identity token capture
• Added cross-site token synchronization
• Added HMAC-SHA256 request signing
• Added timestamp validation
• Added allowed-site validation
• Added optional HTTP Basic Authentication
• Added configurable tracking cookie
• Added configurable token TTL
• Added analytics consent detection
• Added direct consent cookie support
• Added structured consent cookie support
• Added WordPress REST API endpoints
• Added temporary token storage using WordPress transients
• Added browser origin validation
• Added WordPress Admin settings
• Added frontend JavaScript configuration