digital-identity-platform-docs

---

digital-identity-platform-docs / workers/sst-loader/worker

workers/sst-loader/worker

Cloudflare Worker responsible for loader delivery, session bootstrapping, and GTM container script proxying for the platform.

Role in the platform

• Serves the first-party loader script (/l/:loaderToken.js) that initializes client-side logic.
• Handles loader bootstrap (/boot) to resolve site, container, profile, and session state via KV.
• Proxies GTM container scripts (/c/:containerToken.js) while preserving preview/debug behavior.

Request flow

• Runtime Config: Fetched/cached from KV EDGE_CONFIG for every request (fail-open).
• GET /l/:loaderToken.js
  • Returns a dynamically rendered loader JS template with environment-specific URLs injected.
• POST /boot
  • Validates loader + site configuration from KV.
  • Resolves container, site, profile, and session.
  • Persists loader session and cookies (Client-side logic).
  • Returns container metadata and cookie restoration instructions (gated by cookie_restoration flag).
• GET /c/:containerToken.js
  • Resolves Web GTM ID from KV.
  • Proxies gtm.js from Google with cache headers.
• POST /mark-session-detection
  • Forwards session detection signals (or skips if adblock_itp_detection is disabled).

Security & trust boundaries

• KV Storage: Acts as the single source of truth for configuration:
  • EDGE_CONFIG: Runtime features and module gating.
  • SITE_REGISTRY: Site-specific settings (GTM ID, domains).
  • LOADER_TOKEN_MAP: Maps public tokens to internal Container IDs.
• Observability: Direct writes to Cloudflare Analytics Engine (AE) and R2.
  • No external database dependencies.

CORS & browser behavior

• Explicit CORS handling for /boot and /mark-session-detection.
• Allows credentials and custom headers used by the loader.

Error handling

• Returns 400 for malformed client payloads.
• Returns 404 for unknown loaders, sites, or containers.
• Internal errors are surfaced as generic 500 responses (fail-safe).

Observability

• Uses writeLogToAE for structured event logging to Analytics Engine.
• Uses pickR2Bucket for raw log archival to R2 (partitioned by day).
• Session identifiers are generated server-side and returned to the client.

Notes

• This Worker intentionally embeds a large JS template string; it is not executed server-side.
• No request routing occurs beyond explicit path matching.
• Designed for Cloudflare Workers runtime semantics.

Runtime Configuration & Module Gating Architecture

This worker participates in the v2 runtime configuration system:

1. Source of Truth: Fetches config from KV (EDGE_CONFIG) keyed by container ID.
2. Caching: Config is cached in caches.default with a generic TTL (default 60s).
3. Fail-Open: If config is unavailable, the worker proceeds without breaking traffic.

Boot Endpoint Behavior (/boot)

• Cookie Restoration: Controlled by cookie_restoration feature flag.
  • true: Cookies retrieved from KV storage (keyed by _fpid) and returned in restoreCookies.
  • false: restoreCookies is empty.
• Note: Client snippet uses _fpid (writable) to ensure persistence across browser restarts.

Feature Model

• Mandatory Modules: server_proxy, custom_loader, adblock_itp_detection (always on).
• Optional Modules: cookie_restoration, multi_domain.

Variables

• default