Cross-Site Identity Sync

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