Skip to content

Rolling main documentation

Built from commit 1810c763add220dd34fd5faaffe2c69aab1d556f. Content may describe unreleased behavior.

Creative Processing ​

Trusted Server rewrites ad creative HTML and CSS to route resources through first-party domains.

Overview ​

Creative processing has separate auction-response and proxied-response paths. When rewriting is enabled for a path, it rewrites URLs in third-party ad creatives so resources are fetched through the publisher's first-party domain. This provides:

  • First-party delivery: eligible, non-excluded external resource URLs route through the publisher's domain
  • First-party context: cookies and storage use the publisher's domain
  • EC ID integration: configurable ID forwarding to downstream endpoints
  • Tamper resistance: validated, signed URLs prevent in-flight URL substitution
  • Configurable data sharing: forwarding to vendors is per the deployer's configuration

Browser-facing first-party origin ​

Rewritten proxy, click, CSS, srcset, and injected creative TSJS URLs are absolute on [publisher].public_origin. See public origin configuration for the default authority, EC cookie scope, and coordinated upgrade/rollback warning. Relative creative source URLs and excluded third-party URLs remain unchanged. The publisher SSAT/page-bids path retains its explicit request-origin override and does not inject the creative bundle.

The runtime captures the injected classic script's origin when it evaluates, ahead of the parent stamp, and uses that origin for sign/rebuild endpoints. Later DOM or base-element changes cannot retarget those captured endpoints. This is not protection against scripts that run before the runtime: an earlier creative script can shadow document.currentScript and supply a false origin, including for GET rebuild navigation, even while the parent stamp remains unchanged. The pinned stamp still supplies legacy relative navigation and the endpoint fallback when no usable script origin exists.

Both publisher-page and creative-runtime script tags also carry the configured origin in data-ts-public-origin. The runtime captures it once alongside the script origin to recognize already-proxied resources on either origin, requiring the exact /first-party/proxy path. This prevents a publisher-page render guard from proxying a server-generated resource again when the bundle and configured endpoint use different origins. The attribute does not change sign/rebuild endpoint selection or the legacy parent stamp. Like the script source, it is not authenticated against scripts that run before the runtime captures it.

How It Works ​

Processing Triggers ​

The creative rewriters are invoked by independent delivery paths:

  1. Auction adm: Winning-bid HTML returned by POST /auction is optionally sanitized ([auction].sanitize_creatives, opt-in, default false) and rewritten ([auction].rewrite_creatives, default true). Click-through links are wrapped according to [auction].rewrite_clicks, which follows rewrite_creatives when unset.
  2. First-party proxy: Non-streaming text/html and text/css responses fetched through /first-party/proxy are rewritten independently of the auction setting. An explicitly set [auction].rewrite_clicks also applies to links in proxied HTML.
  3. Integration processing: Publisher HTML integrations use their own registration and configuration controls.

Streaming Mode

When with_streaming() is enabled in ProxyRequestConfig, proxied HTML/CSS processing is skipped to preserve origin compression and reduce latency. This does not change the POST /auction sanitizer or rewrite setting.

Auction Rewrite Control ​

Three auction settings control the processing applied to winning-bid adm returned by POST /auction and delivered through the publisher SSAT/page-bids path. Sanitization is opt-in (default false) and asset rewriting is enabled by default. Click wrapping is controlled by rewrite_clicks, which follows rewrite_creatives when unset; see Assets and clicks.

toml
[auction]
sanitize_creatives = false
rewrite_creatives = true
# rewrite_clicks unset: follows rewrite_creatives

Regardless of mode, a creative larger than the 1 MiB per-creative cap is rejected and its adm is dropped.

sanitize_creativesrewrite_creativesAuction winning-bid adm behavior
false (default)falseAsset URLs stay direct. With rewrite_clicks unset or false, deliver the creative exactly as the bidder returned it (subject to the size cap); with rewrite_clicks = true, wrap links as described in Assets and clicks.
truefalseStrip executable markup (script/object/embed/form, event handlers) with its inner content, then deliver without asset rewriting. Sanitizer-accepted external resource and inline CSS URLs remain direct; links follow rewrite_clicks and stay direct when it is unset or false.
falsetrue (default)Rewrite eligible resource/CSS URLs in the raw bidder markup to signed first-party endpoints, dropping any bidder <base> URL. Links are wrapped unless rewrite_clicks = false. Executable markup is preserved.
truetrueSanitize first, then rewrite. POST /auction emits absolute endpoints on the configured public origin and injects creative TSJS exactly once, whether or not the bidder supplied a <body>; SSAT/page-bids retains its request-origin override for its foreign-origin renderer and does not inject the bundle.

Sanitization blanks script-based creatives

Sanitization removes script/object/embed/form and similar elements together with their inner content, which destroys script-based creatives — the majority of programmatic display. Enable sanitize_creatives when creatives render in a context that shares the publisher's origin; leave it disabled when creatives render in a foreign-origin frame (for example the Prebid Universal Creative inside the ad server's iframe), where the markup cannot reach the publisher origin. Sanitizer acceptance is not a host allowlist; ordinary accepted HTTP(S) URLs may cause the browser to contact external creative hosts directly.

Assets and clicks ​

rewrite_creatives governs asset URLs. rewrite_clicks governs click-through links and follows rewrite_creatives when unset:

toml
[auction]
rewrite_creatives = true
# Unset: follows rewrite_creatives. Set false to keep landing links direct.
# rewrite_clicks = false
Assets (rewrite_creatives)Clicks (rewrite_clicks)Asset URLsLinks<base>TSJS on POST /auction
truetrue or unset/first-party/proxy/first-party/click + data-tsclickhref droppedinjected
truefalse/first-party/proxydirecthref droppedinjected
falsetruedirect/first-party/click + data-tsclickhref droppedinjected
falsefalse or unsetdirectdirectkeptnot injected

The endpoint paths in this table are emitted as absolute URLs on publisher.public_origin, falling back to https://{publisher.domain}. SSAT/page-bids follows the same table with its request-origin override and never injects TSJS. The <base> column assumes sanitize_creatives = false; the sanitizer removes <base> entirely before the rewrite pass. exclude_domains applies to both assets and links.

The client-side tsCreativeConfig.clickGuard flag is separate. rewrite_clicks decides whether the server emits signed click URLs; clickGuard decides whether the creative runtime re-signs them after creative script changes their query parameters. With rewrite_clicks off and rewrite_creatives on, the injected guard installs its listeners but never acts, because no link carries data-tsclick.

Both switches also decide where the visitor's EC ID goes. /first-party/click appends the request's ts-ec value to the landing URL and logs the click with it, and /first-party/proxy appends it to proxied asset requests. With rewrite_clicks = false, creative links stop forwarding it on every path; with rewrite_clicks = true and rewrite_creatives = false, landing pages receive it while assets load direct. Neither switch is a consent control: EC issuance is consent-gated, and both endpoints forward whatever EC ID the request carries.

With rewrite_creatives = false and rewrite_clicks = true, POST /auction still injects TSJS, but this does not reopen asset proxying in practice: /auction creatives render in a sandbox without allow-same-origin, so the render guard skips /first-party/sign and script-inserted assets load direct. /first-party/sign itself is not gated by rewrite_creatives.

Whenever either switch is on, a bidder <base> loses its href and keeps target; a <base> without target is removed. With rewrite_creatives = false and rewrite_clicks = true, relative asset URLs therefore no longer resolve against the bidder base, so bidders should use absolute asset URLs. With sanitize_creatives = true the sanitizer removes <base> entirely first.

On POST /auction and in HTML fetched through /first-party/proxy, the injected click guard navigates a data-tsclick link using only the link's own target, not a kept <base target>. A creative that relies on <base target="_blank"> can therefore open wrapped links in the frame and unwrapped links in a new tab; give links an explicit target to avoid this.

Runtime protections inside the sandboxed creative iframe

Creatives rendered by Trusted Server's own path run in a sandboxed iframe without allow-same-origin, i.e. an opaque origin. The injected creative runtime's click guard recovers mutated clicks there via a GET /first-party/proxy-rebuild navigation (302 chain).

Two capabilities are unavailable in that context. CORS-mode subresources — ES modules, crossorigin fonts, fetch/XHR — cannot load through /first-party/proxy, because that endpoint deliberately sends no Access-Control-Allow-Origin: it is a generic signed fetcher that forwards the EC ID and client-derived headers, so letting an opaque creative frame read its responses would turn it into a readable bidder-controlled proxy. Ordinary subresources (<img>, <script src>, stylesheets, media) are unaffected. A separately constrained asset capability is tracked in #982.

The second is dynamic resource signing, which rewrites URLs on elements a creative inserts at runtime. It is installed only when renderGuard is enabled in tsCreativeConfig, and that is false by default — deployments using the default configuration are unaffected. Where it is enabled, runtime-inserted <img>/<iframe> URLs cannot be signed from an opaque origin (the signing request is blocked by CORS), so they load directly from third parties; the sandbox still isolates them from the publisher origin, but they are not first-party proxied. A same-origin parent postMessage broker restoring dynamic signing is tracked in #982. URLs rewritten server-side are unaffected.

PBS Cache coordinates and processing

On the publisher SSAT/page-bids path, hb_cache_host/hb_cache_path let the client fetch and render the cached bid, whose adm is the bidder's original markup and therefore bypasses every server-side processing policy. They are emitted only for bids that supplied no creative of their own, where the cache is the sole render source. A bid that supplied a creative — whether processing accepted it, or rejected it as empty, unparseable, or over the size limit — ships without them, so a processed or refused creative can never be re-fetched raw.

rewrite_creatives and sanitize_creatives do not affect HTML/CSS rewriting under /first-party/proxy; an explicit rewrite_clicks does apply to links there. The publisher SSAT/page-bids path is a production creative path and follows all three settings. [debug].inject_adm_for_testing controls only the additional debug_bid diagnostic blob and testing-only direct GAM replacement; it does not control whether the processed adm is present.

Rewritten Elements ​

Images ​

Elements: <img>, <input type="image">

Attributes:

  • src - Primary image source
  • data-src - Lazy-loading source
  • srcset - Responsive image sources
  • imagesrcset - Image set (used in <link>)

Example:

html
<!-- Original -->
<img
  src="https://cdn.example.com/banner.jpg"
  srcset="
    https://cdn.example.com/banner@1x.jpg 1x,
    https://cdn.example.com/banner@2x.jpg 2x
  "
/>

<!-- Rewritten -->
<img
  src="https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/banner.jpg&tstoken=sig1"
  srcset="
    https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/banner@1x.jpg&tstoken=sig2 1x,
    https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/banner@2x.jpg&tstoken=sig3 2x
  "
/>

Scripts ​

Elements: <script>

Attributes:

  • src - Script source URL

Example:

html
<!-- Original -->
<script src="https://cdn.example.com/tracker.js"></script>

<!-- Rewritten -->
<script src="https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/tracker.js&tstoken=sig"></script>

Media Elements ​

Elements: <video>, <audio>, <source>

Attributes:

  • src - Media source URL

Example:

html
<!-- Original -->
<video>
  <source src="https://cdn.example.com/video.mp4" type="video/mp4" />
</video>

<!-- Rewritten -->
<video>
  <source
    src="https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/video.mp4&tstoken=sig"
    type="video/mp4"
  />
</video>

Embedded Objects ​

Elements: <object>, <embed>

Attributes:

  • data - Object data source (<object>)
  • src - Embed source (<embed>)

Example:

html
<!-- Original -->
<object data="https://example.com/flash.swf"></object>
<embed src="https://example.com/media.swf" />

<!-- Rewritten -->
<object
  data="https://ads.publisher.example/first-party/proxy?tsurl=https://example.com/flash.swf&tstoken=sig"
></object>
<embed
  src="https://ads.publisher.example/first-party/proxy?tsurl=https://example.com/media.swf&tstoken=sig"
/>

Iframes ​

Elements: <iframe>

Attributes:

  • src - Frame source URL

Example:

html
<!-- Original -->
<iframe src="https://advertiser.example.com/creative.html"></iframe>

<!-- Rewritten -->
<iframe
  src="https://ads.publisher.example/first-party/proxy?tsurl=https://advertiser.example.com/creative.html&tstoken=sig"
></iframe>

Nested Iframes

If the iframe content itself contains HTML, it will be processed recursively. Each level of nesting gets its own URL rewriting pass.

Elements: <link>

Attributes:

  • href - Link target (stylesheets, preload, prefetch)
  • imagesrcset - Responsive images in link preload

Conditions: Only rewritten when rel attribute matches:

  • stylesheet
  • preload
  • prefetch

Example:

html
<!-- Original -->
<link rel="stylesheet" href="https://cdn.example.com/styles.css" />
<link rel="preload" href="https://cdn.example.com/font.woff2" as="font" />

<!-- Rewritten -->
<link
  rel="stylesheet"
  href="https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/styles.css&tstoken=sig"
/>
<link
  rel="preload"
  href="https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/font.woff2&tstoken=sig"
  as="font"
/>

Anchors (Click Tracking) ​

Elements: <a>, <area>

Attributes:

  • href - Link destination

Rewrite Mode: Uses /first-party/click for direct redirects

Controlled by: [auction].rewrite_clicks (follows rewrite_creatives when unset; HTML fetched through /first-party/proxy keeps wrapping links when unset)

Example:

html
<!-- Original -->
<a href="https://advertiser.example.com/product?id=123">Buy Now</a>

<!-- Rewritten -->
<a
  href="https://ads.publisher.example/first-party/click?tsurl=https://advertiser.example.com/product&id=123&tstoken=sig"
  data-tsclick="https://ads.publisher.example/first-party/click?tsurl=https://advertiser.example.com/product&id=123&tstoken=sig"
  >Buy Now</a
>

Click vs Proxy

Anchors (<a>) use /first-party/click for 302 redirects, avoiding content downloads. Other elements use /first-party/proxy to fetch and potentially rewrite content.

SVG Elements ​

Elements: SVG <image>, <use>

Attributes:

  • href - SVG 2.0 syntax
  • xlink:href - SVG 1.1 legacy syntax

Example:

html
<!-- Original -->
<svg>
  <image href="https://cdn.example.com/icon.svg" />
  <use xlink:href="https://cdn.example.com/sprite.svg#icon" />
</svg>

<!-- Rewritten -->
<svg>
  <image
    href="https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/icon.svg&tstoken=sig"
  />
  <use
    xlink:href="https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/sprite.svg&tstoken=sig#icon"
  />
</svg>

Inline Styles ​

Attributes: style attribute on any element

Patterns: Rewrites url(...) values in CSS

Example:

html
<!-- Original -->
<div style="background: url(https://cdn.example.com/bg.png) no-repeat;">
  <!-- Rewritten -->
  <div
    style="background: url(https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/bg.png&tstoken=sig) no-repeat;"
  ></div>
</div>

Style Blocks ​

Elements: <style>

Patterns: Rewrites all url(...) occurrences in CSS

Example:

html
<!-- Original -->
<style>
  .header {
    background-image: url(https://cdn.example.com/header.jpg);
  }
  .logo {
    background: url('https://cdn.example.com/logo.png');
  }
</style>

<!-- Rewritten -->
<style>
  .header {
    background-image: url(https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/header.jpg&tstoken=sig);
  }
  .logo {
    background: url('https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/logo.png&tstoken=sig');
  }
</style>

URL Detection Rules ​

Absolute URLs ​

Pattern: Starts with http:// or https://

Rewritten: ✅ Yes

Examples:

✅ https://cdn.example.com/image.png
✅ http://tracker.example.com/pixel.gif
❌ /relative/path.jpg (relative)
❌ ../images/logo.png (relative)

Protocol-Relative URLs ​

Pattern: Starts with //

Rewritten: ✅ Yes (normalized to https://)

Examples:

Original: //cdn.example.com/script.js
Normalized: https://cdn.example.com/script.js
Rewritten: https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/script.js&tstoken=sig

Relative URLs ​

Patterns:

  • Starts with / (absolute path)
  • Starts with ./ or ../ (relative path)
  • No scheme prefix (relative)

Rewritten: ❌ No

Examples:

❌ /assets/image.png
❌ ./local.jpg
❌ ../parent/file.css
❌ image.png

Why Skip Relative URLs?

Relative URLs already point to your domain (publisher origin). Rewriting them would create unnecessary proxy loops and break functionality.

Non-Network Schemes ​

Skipped Schemes:

  • data: - Data URIs (inline content)
  • javascript: - JavaScript execution
  • mailto: - Email links
  • tel: - Phone numbers
  • blob: - Blob objects
  • about: - Browser internal pages

Rewritten: ❌ No

Examples:

❌ data:image/png;base64,iVBORw0KGgo...
❌ javascript:void(0)
❌ mailto:contact@example.com
❌ tel:+1234567890
❌ blob:https://example.com/uuid
❌ about:blank

Srcset Processing ​

Srcset Syntax ​

Srcset attributes contain comma-separated candidates with optional descriptors:

Format: url descriptor, url descriptor, ...

Descriptors:

  • 1x, 2x, 3x - Pixel density
  • 100w, 200w - Width in pixels

Parsing Rules ​

Robust Comma Handling:

  • Splits on commas with or without spaces
  • Preserves data: URIs (doesn't split on internal commas)
  • Handles irregular spacing

Example:

html
<!-- Various spacing patterns -->
srcset="url1.jpg 1x, url2.jpg 2x"
<!-- standard -->
srcset="url1.jpg 1x,url2.jpg 2x"
<!-- no space after comma -->
srcset="url1.jpg 1x , url2.jpg 2x"
<!-- extra spaces -->

Descriptor Preservation ​

Descriptors are preserved exactly as written:

html
<!-- Original -->
<img
  srcset="
    https://cdn.example.com/small.jpg   480w,
    https://cdn.example.com/medium.jpg  800w,
    https://cdn.example.com/large.jpg  1200w
  "
/>

<!-- Rewritten -->
<img
  srcset="
    https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/small.jpg&tstoken=sig1   480w,
    https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/medium.jpg&tstoken=sig2  800w,
    https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/large.jpg&tstoken=sig3  1200w
  "
/>

Mixed URL Types ​

Srcset can mix absolute and relative URLs:

html
<!-- Original -->
<img srcset="/local/small.jpg 1x, https://cdn.example.com/large.jpg 2x" />

<!-- Rewritten (only absolute URL) -->
<img
  srcset="
    /local/small.jpg                                                                                    1x,
    https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/large.jpg&tstoken=sig 2x
  "
/>

CSS URL Rewriting ​

url() Syntax Variations ​

CSS url() values support multiple quote styles:

css
/* No quotes */
url(https://example.com/image.png)

/* Single quotes */
url('https://example.com/image.png')

/* Double quotes */
url("https://example.com/image.png")

/* With spaces */
url(  "https://example.com/image.png"  )

All are rewritten correctly, preserving the original quote style.

CSS Properties ​

Common properties with url() values:

css
/* Background images */
background: url(https://cdn.example.com/bg.jpg);
background-image: url(https://cdn.example.com/pattern.png);

/* Borders */
border-image: url(https://cdn.example.com/border.svg);

/* List styles */
list-style-image: url(https://cdn.example.com/bullet.png);

/* Cursors */
cursor: url(https://cdn.example.com/cursor.cur), pointer;

/* Masks */
mask-image: url(https://cdn.example.com/mask.svg);

/* Filters */
filter: url(https://cdn.example.com/filter.svg#blur);

All url() occurrences are rewritten regardless of property.

Multiple url() Values ​

Properties can have multiple url() values:

css
/* Original */
.element {
  background:
    url(https://cdn.example.com/top.png) top,
    url(https://cdn.example.com/bottom.png) bottom;
}

/* Rewritten */
.element {
  background:
    url(https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/top.png&tstoken=sig1)
      top,
    url(https://ads.publisher.example/first-party/proxy?tsurl=https://cdn.example.com/bottom.png&tstoken=sig2)
      bottom;
}

@import Rules ​

CSS @import with URLs:

css
/* Original */
@import url(https://fonts.example.com/css?family=Roboto);

/* Rewritten */
@import url(https://ads.publisher.example/first-party/proxy?tsurl=https://fonts.example.com/css?family=Roboto&tstoken=sig);

Exclude Domains ​

Configuration ​

Prevent specific domains from being rewritten:

toml
[rewrite]
exclude_domains = [
  "*.cdn.trusted-partner.com",  # Wildcard pattern
  "first-party.example.com",    # Exact match
  "localhost",                  # Development
]

Pattern Matching ​

Matching is case-insensitive. Entries are trimmed and lowercased at load.

Wildcard Patterns: *. matches the base domain and any subdomain

Pattern: *.cdn.example.com
Matches:
  ✅ assets.cdn.example.com
  ✅ images.cdn.example.com
  ✅ cdn.example.com (apex also matches)
  ❌ cdn.example.com.evil.com (different domain)

Matching is case-insensitive.

Exact Patterns: No * requires exact host match

Pattern: api.example.com
Matches:
  ✅ api.example.com
  ❌ www.api.example.com
  ❌ api.example.com.evil.com

Use Cases ​

Trusted Partners:

toml
exclude_domains = ["*.trusted-cdn.example.com"]

Skip rewriting for partners already providing first-party scripts.

Development:

toml
exclude_domains = ["localhost", "127.0.0.1"]

Avoid proxying local development servers.

Same-Origin Resources:

toml
exclude_domains = ["assets.publisher.com"]

Skip resources already on your domain.

Include Domains ​

Limit asset rewriting to hosts you list:

toml
[rewrite]
include_domains = ["assets.example.com", "*.img.example.com"]
  • When include_domains is empty (the default), every eligible asset URL is proxied.
  • When it is non-empty, only asset URLs whose host matches an entry are rewritten to /first-party/proxy. Other assets keep their original URL, load directly, and do not receive the EC ID that proxied fetches append.
  • exclude_domains wins when a host matches both lists.
  • Click-through links (<a href>, <area href>) are not affected. Whether they are wrapped in /first-party/click depends only on rewrite_clicks (which follows rewrite_creatives on the auction paths when unset) and exclude_domains.
  • HTML and CSS fetched through /first-party/proxy go through the same rewrite pass and follow the same list.
  • /first-party/sign declines off-list hosts with a non-403 error, so the creative runtime loads them directly.

Patterns use the same syntax as exclude_domains. Entries that can never equal a URL host, such as ones with a scheme, port, path or non-ASCII name, fail validation; see Pattern Matching.

Integration Hooks ​

Attribute Rewriters ​

Integrations can override attribute rewriting:

Example: Next.js integration rewrites origin URLs

rust
impl IntegrationAttributeRewriter for NextJsIntegration {
    fn rewrite(&self, attr_name: &str, attr_value: &str, ctx: &Context)
        -> AttributeRewriteAction
    {
        if attr_name == "href" && attr_value.contains(&ctx.origin_host) {
            let rewritten = attr_value.replace(&ctx.origin_host, &ctx.request_host);
            return AttributeRewriteAction::replace(rewritten);
        }
        AttributeRewriteAction::keep()
    }
}

Actions:

  • keep() - Leave attribute unchanged
  • replace(value) - Change attribute value
  • remove_element() - Delete entire element

Script Rewriters ​

Integrations can modify <script> content:

Example: Next.js rewrites __NEXT_DATA__ JSON

rust
impl IntegrationScriptRewriter for NextJsIntegration {
    fn selector(&self) -> &'static str {
        "script#__NEXT_DATA__"
    }

    fn rewrite(&self, content: &str, ctx: &Context) -> ScriptRewriteAction {
        let rewritten = rewrite_next_data_urls(content, ctx);
        ScriptRewriteAction::replace(rewritten)
    }
}

Actions:

  • keep() - Preserve the current working text fragment
  • replace(content) - Pass replacement text to subsequent matching stages
  • remove_node() - Suppress this text fragment, not the <script> element

Matching script rewriters compose in registration order. Each receives the previous stage's output, including empty suppressed text, with the original final-fragment flag. Downstream stages still run after remove_node() and may flush buffered text. Only the composed result is applied to the parser fragment; script replacements are emitted as raw source, not HTML-entity-escaped text. Selectors must match <script> elements; non-script text hooks are unsupported.

Head Injectors ​

Integrations can inject HTML snippets at the start of <head>, immediately after the unified TSJS bundle:

Example: An integration injects configuration that runs after the TSJS API is available

rust
impl IntegrationHeadInjector for MyIntegration {
    fn integration_id(&self) -> &'static str { "my_integration" }

    fn head_inserts(&self, ctx: &IntegrationHtmlContext<'_>) -> Vec<String> {
        vec![format!(
            r#"<script>tsjs.setConfig({{ host: "{}" }});</script>"#,
            ctx.request_host
        )]
    }
}

Behavior:

  • Snippets are prepended into <head> after the TSJS bundle tag
  • Called once per HTML response
  • Multiple integrations can each contribute snippets
  • If no snippets are returned, no extra markup is added

See Integration Guide for creating custom rewriters.

TSJS Injection ​

Automatic Injection ​

The Trusted Server JavaScript (TSJS) library is automatically injected:

Location: Start of <head> element

Tag:

html
<script
  src="/static/tsjs=tsjs-unified.min.js?v=<hash>"
  id="trustedserver-js"
></script>

Timing: Injected once per HTML response before any other scripts.

The tag above illustrates publisher HTML injection. Creative HTML injection uses an absolute URL such as https://ads.publisher.example/static/tsjs=tsjs-unified.min.js?v=<hash>. Changing the URL authority does not change the selected modules or hash.

Integration bundles ​

The integration registry selects TSJS modules by enabled integration ID. A registered ID with a compiled module is included in the immediate unified bundle unless its builder calls .with_deferred_js(); deferred modules are served separately as /static/tsjs=tsjs-<id>.min.js. Builders can call .without_js() when the Rust integration must not select a TSJS module.

The always-present creative module and all immediate integration modules are served through /static/tsjs=tsjs-unified.min.js. Trusted Server does not accept an arbitrary asset name from an integration registration.

Bundle Types ​

Each integration is built as a separate IIFE at compile time (into Cargo's OUT_DIR; npm run build writes the same files to crates/trusted-server-js/dist/):

  • tsjs-core.js — Core API (always included)
  • tsjs-creative.js — Creative click-guard and tracking
  • Prebid is built externally with build-prebid-external.mjs and served through /integrations/prebid/bundle.js
  • tsjs-lockr.js, tsjs-permutive.js, tsjs-didomi.js, tsjs-datadome.js, tsjs-testlight.js — Other integrations

At runtime, the server concatenates tsjs-core.js + the modules for enabled integrations. The path stays /static/tsjs=tsjs-unified.min.js?v=<hash>. Injected creative script URLs prefix that path with the configured public origin. Bundle selection and hash calculation are unchanged.

Performance Optimization ​

Streaming Processing ​

HTML is processed in chunks (default 8192 bytes):

Benefits:

  • Low memory footprint
  • Handles large creatives
  • Incremental output
  • Fast first byte

Trade-offs:

  • Cannot access full DOM
  • Element-by-element processing
  • No look-ahead

Compression ​

Buffered Mode (with rewriting):

Origin Response (gzipped)
  ↓ Decompress
Processing
  ↓ Rewrite URLs
Response (uncompressed)
  ↓ Fastly edge can re-compress
Client

Streaming Mode (no rewriting):

Origin Response (gzipped)
  ↓ Passthrough
Client (stays gzipped)

Use streaming for binary/large files to preserve compression.

Caching ​

Rewritten creatives can be cached:

Cache Key Components:

  • Original creative URL
  • Publisher domain
  • Integration configuration

Headers to Set:

http
Cache-Control: public, max-age=3600
Vary: Accept-Encoding

Debugging ​

Logging ​

Enable debug logging for rewrite operations:

rust
log::debug!("creative: rewriting {} -> {}", original_url, proxy_url);
log::debug!("creative: excluded domain {}", url);
log::debug!("creative: skipped non-network scheme {}", url);

Testing Rewrites ​

Manual Testing:

  1. Save original creative HTML to file
  2. Pass through rewrite function
  3. Compare output
rust
let original = "<img src=\"https://tracker.com/pixel.gif\">";
let rewritten = rewrite_creative_html(&settings, original);
assert!(rewritten.contains("/first-party/proxy"));

Integration Tests:

rust
#[test]
fn test_image_src_rewrite() {
    let html = r#"<img src="https://cdn.example.com/banner.jpg">"#;
    let result = rewrite_creative_html(&test_settings(), html);
    assert!(result.contains("/first-party/proxy?tsurl="));
    assert!(result.contains("&tstoken="));
}

Common Issues ​

Relative URLs Not Working:

  • The rewriter drops a <base> href, so relative URLs do not resolve against it
  • Convert relative URLs to absolute URLs before rewriting

Data URIs Being Rewritten:

  • Should be automatically skipped
  • Check for malformed data: scheme

Srcset Parsing Errors:

  • Verify comma-separated format
  • Check for unclosed quotes

Security Considerations ​

URL Validation ​

All rewritten URLs are validated:

  1. Scheme Check: Only http:// and https://
  2. Signature: HMAC-SHA256 token required
  3. Expiration: Optional tsexp timestamp
  4. Exclusion List: Configurable domain blacklist

Content Security Policy ​

Recommended CSP headers for rewritten creatives:

http
Content-Security-Policy:
  default-src 'self';
  img-src 'self' /first-party/proxy;
  script-src 'self' /static/tsjs;
  style-src 'self' 'unsafe-inline';
  frame-src 'self' /first-party/proxy;

Injection Prevention ​

Automatic Protection:

  • URLs are properly encoded
  • No raw user input in rewrites
  • Signature prevents tampering

Manual Checks:

  • Validate origin creative sources
  • Sanitize user-generated content
  • Monitor for suspicious patterns

Best Practices ​

Configuration ​

✅ Do:

  • Use strong proxy_secret (32+ bytes random)
  • Exclude trusted first-party domains
  • Set appropriate cache headers
  • Test rewrites before production

❌ Don't:

  • Hardcode secrets in source
  • Rewrite same-origin URLs unnecessarily
  • Skip signature validation
  • Disable TSJS injection without reason

Performance ​

✅ Do:

  • Use streaming for large/binary responses
  • Enable compression at edge
  • Cache rewritten creatives
  • Monitor rewrite latency

❌ Don't:

  • Buffer entire response unnecessarily
  • Rewrite on every request (cache!)
  • Process non-HTML/CSS with rewriter
  • Chain multiple rewrites

Monitoring ​

Track these metrics:

  • Rewrite operations - Count of rewrites per request
  • Excluded domains - Frequency of exclusions
  • Processing time - Latency added by rewriting
  • Cache hit rate - Effectiveness of caching
  • TSJS injection - Verify library loads

Next Steps ​

Released under the Apache License 2.0.