diff --git a/crates/common/src/integrations/datadome.rs b/crates/common/src/integrations/datadome.rs new file mode 100644 index 00000000..f71df8ee --- /dev/null +++ b/crates/common/src/integrations/datadome.rs @@ -0,0 +1,818 @@ +//! `DataDome` integration for bot protection and security. +//! +//! This module provides transparent proxying for `DataDome`'s JavaScript tag and signal +//! collection API, enabling first-party bot protection while maintaining the permissionless +//! Trusted Server approach (no DNS/CNAME changes required). +//! +//! # Overview +//! +//! `DataDome` provides real-time bot protection and fraud prevention. This integration enables +//! first-party delivery of `DataDome`'s JavaScript SDK and signal collection through Trusted +//! Server, eliminating the need for DNS/CNAME configuration while improving protection against +//! ad blockers that may interfere with third-party scripts. +//! +//! # Benefits +//! +//! - **No DNS changes required**: Works immediately without CNAME setup +//! - **First-party context**: All traffic flows through the publisher's domain +//! - **Ad blocker resistance**: First-party scripts are less likely to be blocked +//! - **Automatic URL rewriting**: SDK scripts are transparently rewritten to use first-party paths +//! +//! # Configuration +//! +//! Add to `trusted-server.toml`: +//! +//! ```toml +//! [integrations.datadome] +//! enabled = true +//! sdk_origin = "https://js.datadome.co" # SDK script origin +//! api_origin = "https://api-js.datadome.co" # Signal collection API origin +//! cache_ttl_seconds = 3600 # Cache TTL for tags.js (1 hour) +//! rewrite_sdk = true # Rewrite DataDome URLs in HTML +//! ``` +//! +//! # Endpoints +//! +//! | Method | Path | Description | +//! |--------|------|-------------| +//! | `GET` | `/integrations/datadome/tags.js` | Proxies the `DataDome` SDK script | +//! | `GET/POST` | `/integrations/datadome/js/*` | Proxies signal collection API calls | +//! +//! # Request Flow +//! +//! 1. **SDK Loading**: Browser requests `/integrations/datadome/tags.js` +//! 2. **Proxy & Rewrite**: Trusted Server fetches from `js.datadome.co`, rewrites internal +//! URLs to first-party paths using [`DATADOME_URL_PATTERN`] +//! 3. **Signal Collection**: SDK sends signals to `/integrations/datadome/js/` +//! 4. **Transparent Proxy**: Trusted Server forwards to `api-js.datadome.co`, returns response +//! +//! # HTML Attribute Rewriting +//! +//! When `rewrite_sdk = true`, the integration implements [`IntegrationAttributeRewriter`] to +//! automatically rewrite `DataDome` script URLs in HTML responses: +//! +//! - ` + +``` + +If `rewrite_sdk` is enabled, Trusted Server will automatically rewrite any existing DataDome script tags in your HTML: + +```html + + + + + +``` + +## Endpoints + +The integration exposes the following routes: + +| Method | Path | Description | +| ---------- | -------------------------------- | --------------------- | +| `GET` | `/integrations/datadome/tags.js` | DataDome SDK script | +| `GET/POST` | `/integrations/datadome/js/*` | Signal collection API | + +## How It Works + +```mermaid +sequenceDiagram + participant Browser + participant TS as Trusted Server + participant SDK as js.datadome.co + participant API as api-js.datadome.co + + Browser->>TS: GET /integrations/datadome/tags.js + TS->>SDK: GET /tags.js + SDK-->>TS: JavaScript SDK + Note over TS: Rewrite internal URLs + TS-->>Browser: Modified SDK (first-party URLs) + + Browser->>TS: POST /integrations/datadome/js/ + TS->>API: POST /js/ + API-->>TS: Response + TS-->>Browser: Response +``` + +### Request Flow + +1. **SDK Loading**: Browser requests `/integrations/datadome/tags.js` +2. **Proxy & Rewrite**: Trusted Server fetches from `js.datadome.co`, rewrites internal URLs to first-party paths +3. **Signal Collection**: SDK sends signals to `/integrations/datadome/js/` +4. **Transparent Proxy**: Trusted Server forwards to `api-js.datadome.co`, returns response + +## Environment Variables + +Override configuration via environment variables: + +```bash +TRUSTED_SERVER__INTEGRATIONS__DATADOME__ENABLED=true +TRUSTED_SERVER__INTEGRATIONS__DATADOME__SDK_ORIGIN=https://js.datadome.co +TRUSTED_SERVER__INTEGRATIONS__DATADOME__API_ORIGIN=https://api-js.datadome.co +TRUSTED_SERVER__INTEGRATIONS__DATADOME__CACHE_TTL_SECONDS=3600 +TRUSTED_SERVER__INTEGRATIONS__DATADOME__REWRITE_SDK=true +``` + +## Client-Side Script Guard + +For single-page applications (SPAs) and frameworks like Next.js that dynamically insert script tags, the integration includes a client-side guard. When the `datadome` module is included in your tsjs bundle, it automatically intercepts dynamically inserted DataDome scripts and rewrites them to use first-party paths. + +The guard handles: + +- `