CRM Sync — Feature Specification Addendum

UA → GA4 Migration, Connected Data Streams & Trust Network DevOps

Document ID: CRM-FEAT-002 Version: 1.0 Date: 2026-05-17 Status: Draft — Architecture Review Parent: CRM-FUNC-SPEC-001 v1.2

1. Executive Summary

This addendum covers three interconnected initiatives:

1. Migration from manual CSV / Universal Analytics (UA) shaped data to real-time GA4 + multi-CDP connected streams
2. Security & compliance hardening with per-stream audit logging, UCP consent provenance, and agentic payment criteria
3. Trust Network DevOps — a non-destructive, forward-deploy model that links cross-channel configuration management to security posture, enabling safe continuous delivery across all paired data streams

The core thesis: replacing fragile, manual, CSV-driven data handoffs with authenticated, logged, consent-aware API streams — and managing the configuration of those streams through a trust-chain deployment model that makes every change auditable, reversible, and compliance-ready before it reaches production.

2. UA → GA4 Data Shape Migration

2.1 What Changes

2.2 Client-Side Consent Migration

Current state: CRM Sync's cookie consent banner writes consent to consent_records and fires consent_mode update. The signal shape needs upgrading to v2.

Target state:

┌──────────────────────────────────────────────────────────┐
│  Consent Banner (Webflow Embed)                          │
│                                                          │
│  User toggles → POST /auth/consent-sync                  │
│       ↓                                                  │
│  gtag('consent', 'update', {                             │
│    ad_storage: 'granted' | 'denied',                     │
│    analytics_storage: 'granted' | 'denied',              │
│    ad_user_data: 'granted' | 'denied',        ← NEW v2  │
│    ad_personalization: 'granted' | 'denied',  ← NEW v2  │
│    functionality_storage: 'granted',                     │
│    security_storage: 'granted'                           │
│  });                                                     │
│       ↓                                                  │
│  DataLayer push → GTM picks up → GA4 respects signals    │
│       ↓                                                  │
│  Worker logs to consent_records with v2 fields            │
└──────────────────────────────────────────────────────────┘

Mapping from CRM consent types to GA4 consent_mode v2:

2.3 Server-Side User Data (Shopify → GA4)

Current state: Server-side MP v2 pushes user properties on tag mutations. Already GA4-native.

Enhancement needed: Add consent_mode v2 signals to server-side events:

// Current (already implemented)
user_properties: {
  crm_status: { value: "active" },
  crm_tier: { value: "vip" },
  consent_marketing: { value: "granted" }
}

// Enhanced: add consent object to event params
consent: {
  ad_storage: "denied",
  analytics_storage: "granted",
  ad_user_data: "denied",
  ad_personalization: "denied"
}

2.4 Migration Steps

3. Connected Data Streams — From CSV to Real-Time

3.1 The Problem with CSV

Manual CSV workflows have these failure modes:

3.2 Per-Stream Sync Logging

Each downstream CDP gets its own sync log table, modeled after adobe_sync_log:

Every log entry records: what data was sent, to which system, whether it succeeded, and what error occurred. The UCP Dashboard can display sync history per user across all streams.

3.3 Consent-Gated Stream Architecture

User Mutation (tag change, form, consent toggle)
  │
  ├─► consent_records (audit — always logged)
  │
  ├─► Check consent state per stream:
  │     ├─ GA4: requires analytics_storage = granted
  │     ├─ Adobe AEP: requires adobe_aep_enabled + marketing consent
  │     ├─ Salesforce: requires salesforce_enabled + marketing consent
  │     ├─ Klaviyo: requires klaviyo_enabled + email consent
  │     ├─ HubSpot: requires hubspot_enabled + marketing consent
  │     ├─ Braze: requires braze_enabled + push/email consent
  │     └─ Attentive: requires attentive_enabled + sms consent
  │
  ├─► Push to consented streams only
  │
  └─► Log result to per-stream sync_log

3.4 Agentic Payment Criteria

When an AI agent makes payment or entitlement decisions, it needs auditable state:

The agent MUST NOT process a payment or data action unless:

1. The user has an active, verified identity
2. The relevant consent is granted (not denied or missing)
3. The tenant has an active subscription at the required tier
4. The target stream sync is healthy (last sync_status = success)

3.5 Data Sunset Plan

3.6 Logging History for UCP Compliance

The UCP Dashboard must show users:

1. Consent history — every consent change with timestamp, source, and which systems were notified
2. Data flow log — which systems have their data, when it was last synced, and the sync status
3. Export log — when their data was exported (data portability requests)
4. Deletion log — confirmation that their data was redacted from all systems

This is the basis for GDPR Art. 15 (right of access) and Art. 30 (records of processing).

4. Trust Network DevOps — Scaling Deploy with Linked Security

4.1 The Trust Network Model

Traditional deployment treats security as a gate at the end of the pipeline — build, test, deploy, then audit. The Trust Network inverts this: security is the deployment topology itself. Every node in the system (Worker, KV, Xano, Shopify, Webflow, GA4, Adobe AEP) is a trust boundary, and the deployment model ensures that changes propagate through the trust chain in a verifiable, non-destructive sequence.

┌─────────────────────────────────────────────────────────────────┐
│                    TRUST NETWORK TOPOLOGY                       │
│                                                                 │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐                │
│  │  Content  │────►│  Review  │────►│  Deploy  │                │
│  │  (Author) │     │  (Verify)│     │ (Forward)│                │
│  └────┬─────┘     └────┬─────┘     └────┬─────┘                │
│       │                │                │                       │
│       ▼                ▼                ▼                       │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐                │
│  │   Dev    │     │  Staging │     │Production │                │
│  │  Config  │────►│  Config  │────►│  Config   │                │
│  └────┬─────┘     └────┬─────┘     └────┬─────┘                │
│       │                │                │                       │
│       └────────────────┴────────────────┘                       │
│                        │                                        │
│              Cross-Channel Config                               │
│              Management Layer                                   │
└─────────────────────────────────────────────────────────────────┘

4.2 Advantages of Scaling DevOps Deploy

A. Configuration-as-Code Across All Channels

Every integration (Shopify, Webflow, GA4, Adobe, Salesforce, etc.) is configured via the same tenant config object in KV. This means:

B. Linked Security Benefit

When configuration management is linked to the security model, you get compounding benefits:

1. Auth gate = deploy gate. The same ADMIN_KEY that protects admin endpoints also gates config writes. If you can't authenticate, you can't deploy config. This means the deploy credential IS the security credential — there's no separate "deploy key" that can be compromised independently.

1. Tenant isolation = blast radius containment. A bad config deploy to tenant:shop-a:config cannot affect tenant:shop-b:config. The multi-tenant KV structure means every "deploy" (config change) is scoped to exactly one tenant. There is no global config that can break all tenants simultaneously (except platform:config, which is separately protected).

1. Consent state follows config. When you enable a new stream (e.g., salesforce_enabled: true), the worker immediately starts checking consent before pushing data. The security posture (consent enforcement) is embedded in the runtime, not in the deploy pipeline. You cannot accidentally deploy a stream that bypasses consent.

1. Credential rotation is a config write. Rotating a Shopify token, Webflow token, or Adobe credential is a POST /config — the same authenticated, logged, reversible operation as any other config change. No redeploy, no downtime, no code change.

1. Zero Trust at the edge. Cloudflare Access (OTP) protects browser access to admin UIs. Bearer tokens protect API access. JWT protects user sessions. HMAC protects webhooks. These four layers are independent — compromising one doesn't compromise the others. And because the worker runs at the Cloudflare edge, there's no origin server to attack.

C. Cross-Channel Configuration Management

The key insight: every downstream system (Shopify, Webflow, GA4, Adobe, Salesforce, Klaviyo, HubSpot, Braze, Attentive) has its own credentials, its own rate limits, its own schema, and its own failure modes. Managing these independently is a combinatorial explosion. Managing them through a single config object with per-stream toggles reduces the problem to:

For each stream S in tenant config:
  if S.enabled AND user.consent[S.required_consent] == granted:
    push(data, S.credentials)
    log(sync_log[S], result)

This pattern scales linearly with the number of streams, not exponentially. Adding a new CDP (e.g., Attentive) requires:

1. Add fields to CrmSiteConfig interface (attentive_enabled, attentive_api_key, attentive_subscriber_list_id)
2. Add a pushAttentiveEvent() function
3. Add attentive_sync_log table
4. Wire into the consent-gated push chain
5. Add to the Webflow extension UI

No new auth model, no new deploy pipeline, no new security review — it inherits the existing trust network.

4.3 Non-Destructive Agile Methods

Forward Deploy (Never Rollback Code)

The worker is a single TypeScript file deployed to Cloudflare Workers. The deployment model is:

The Four-Phase Trust Cycle

1. CONTENT (Author)
   └─ Developer writes code or config change
   └─ Change is scoped: which tenant, which stream, which fields
   └─ PR or config POST with description

2. DEVELOPMENT (Build + Test)
   └─ wrangler dev — local worker with real KV bindings
   └─ Webflow extension serve — local UI testing
   └─ Smoke tests (tests/smoke-test.sh) validate all auth gates
   └─ Compliance harness (tests/compliance-harness.ts) validates data contracts

3. REVIEW (Verify)
   └─ Security: all admin routes return 401 without bearer token
   └─ Privacy: no PII in logs, embeds, or client-side code
   └─ Consent: every stream push checks consent state
   └─ Config: secrets masked in GET /config
   └─ Tenant isolation: config writes scoped to tenant:{shop}

4. FORWARD DEPLOY (Ship)
   └─ wrangler deploy — immutable version created
   └─ Config write (if needed) — POST /config?shop=target
   └─ Feature toggle — enable new stream per-tenant
   └─ Monitor — /health, sync_logs, error rates
   └─ No rollback needed — fix forward with next deploy + config write

Why Non-Destructive Matters

Every operation in CRM Sync is designed to be additive. The system appends consent records, upserts customer profiles, merges config fields, and logs every outbound push. The only truly destructive operation is GDPR redaction — and even that preserves the consent audit trail (as legally required).

4.4 Security Posture Scaling

As the number of connected streams grows, the security surface area grows with it. The trust network model ensures this growth is manageable:

Streams: 1 → 3 → 7 → 12
         │    │    │    │
         │    │    │    └─ Same bearer token auth
         │    │    └────── Same consent enforcement
         │    └─────────── Same sync_log pattern
         └──────────────── Same tenant isolation

Security work scales O(1) per new stream, not O(n).

Each new CDP integration inherits:

• Bearer token auth on admin endpoints (already implemented)
• Consent check before push (pattern exists)
• Sync log table (schema templated)
• Tenant-scoped credentials (config structure exists)
• Feature flag toggle (config boolean)
• PII hashing (SHA-256 helper exists)
• UCP visibility (Dashboard can read sync_logs)

The only stream-specific work is: API client code, field mapping, and error handling — the security, consent, logging, and deployment infrastructure is reused.

5. Implementation Roadmap

Phase 1: GA4 Consent v2 + Logging (Week 1-2)

Phase 2: Connected Stream Infrastructure (Week 3-4)

Phase 3: CDP Integrations — Enterprise Tier (Week 5-8)

Phase 4: Agentic Payment + Data Sunset (Week 9-10)

6. React Compiler in Webflow Code Managers — Resolved Security Issues

6.1 Context

Webflow Designer Extensions (Code Managers) are React applications running inside the Webflow Designer. CRM Auth and PIM Sync both render config UIs, credential inputs, consent toggles, and sync controls. These extensions handle sensitive state: API keys, OAuth tokens, tenant config, and consent preferences. Bringing React Compiler (automatic memoization / React Forget) into these Code Managers — compiled and served via Cloudflare Workers with Xano as the data layer — resolves an entire class of security issues that exist in hand-optimized React code.

6.2 Security Issues Resolved

A. Stale Closure Credential Leaks

Problem: Manual useCallback/useMemo with incorrect dependency arrays create stale closures. A config form that caches an old adminKey value in a stale closure can send the wrong credential, or worse, send a revoked credential that was supposed to be rotated.

React Compiler fix: Automatic memoization tracks all reactive dependencies at compile time. The compiler guarantees that every closure captures current values — no stale credentials, no phantom token references.

B. Re-Render State Exposure

Problem: Unnecessary re-renders in config panels can briefly expose intermediate state — a half-typed API key in a text input triggers a render cycle that passes the partial value to a child component, which may log it, send it in analytics, or display it in a non-masked field.

React Compiler fix: Optimal memoization means components only re-render when their actual inputs change. Intermediate state stays contained in the component that owns it. No cascading renders that leak partial credentials down the tree.

C. Side-Effect Timing in OAuth Flows

Problem: OAuth callback handling in Designer Extensions involves receiving tokens, storing them, and updating UI state. In hand-optimized React, useEffect timing bugs can cause:

• Token written to Xano after UI shows "connected" (race condition)
• Double-fetch of token exchange endpoint (no cleanup in strict mode)
• State update on unmounted component during redirect (memory leak + error)

React Compiler fix: The compiler understands the reactive graph and produces correctly-timed effects. Combined with Cloudflare Workers handling the actual OAuth exchange server-side, the extension UI becomes a pure display layer — it reads token status from the worker, not from local effect chains.

D. Immutable Config Enforcement

Problem: Mutable state objects in React can be accidentally shared across components. If two tabs in the CRM Auth extension (Config tab and Status tab) reference the same config object and one mutates it, the other sees corrupted state. In a security context, this can mean:

• Consent toggles showing wrong state (user thinks marketing is off, but it's on)
• Config diff showing no change when credentials were actually modified
• Sync status reflecting a different tenant's state

React Compiler fix: React Compiler requires (and enforces at compile time) immutable data patterns. Mutations are flagged as errors during compilation. Every state update produces a new object, so cross-component state corruption is structurally impossible.

E. Bundle Integrity via Compile-Time Validation

Problem: Webflow Designer Extensions ship as a bundle.zip containing compiled JS. Without compile-time validation, runtime bugs in production are invisible until a user hits them — and in a security-sensitive Code Manager, "runtime bug" can mean "credential sent to wrong endpoint" or "consent state not checked."

React Compiler fix: The compilation step acts as a static analysis gate. Code that violates React's rules of hooks, mutates state directly, or creates non-deterministic renders fails compilation. This means:

TypeScript compile → React Compiler validate → Bundle → Upload to Webflow
                          ↑
                    Security gate:
                    - No stale closures
                    - No mutable state sharing  
                    - No effect timing bugs
                    - No hook rule violations

The bundle that reaches Webflow Designer has been structurally verified — not just type-checked, but semantically validated for correct reactive behavior.

6.3 Cloudflare Workers as Secure Computation Boundary

React Compiler in the extension UI is half the story. The other half is what code runs in the Worker vs. what runs in the extension:

The React Compiler ensures the extension UI is a correct, minimal display layer. Cloudflare Workers ensure all security-critical computation happens server-side. Xano ensures all data persistence is behind authenticated API calls. No single layer can compromise the system alone.

6.4 Xano Tool Integration Security

Xano serves as the authenticated data layer behind both the Worker and the extension. React Compiler improves the extension↔Xano interaction:

6.5 Summary: Compound Security Stack

┌─────────────────────────────────────────────────────────┐
│                COMPILE-TIME (React Compiler)             │
│  ✓ No stale closures   ✓ Immutable state enforced       │
│  ✓ Correct effect timing  ✓ Hook rules validated         │
├─────────────────────────────────────────────────────────┤
│                EDGE RUNTIME (Cloudflare Workers)         │
│  ✓ No origin server    ✓ KV encrypted at rest           │
│  ✓ Bearer/JWT/HMAC auth  ✓ Tenant isolation             │
├─────────────────────────────────────────────────────────┤
│                DATA LAYER (Xano)                         │
│  ✓ Authenticated API only  ✓ Append-only audit logs     │
│  ✓ Schema validation       ✓ Role-based access          │
├─────────────────────────────────────────────────────────┤
│                GATEWAY (Webflow)                         │
│  ✓ Extension sandboxed in Designer  ✓ Bundle verified   │
│  ✓ No direct DB access  ✓ CMS token scoped per site    │
└─────────────────────────────────────────────────────────┘

Each layer resolves a different attack surface. React Compiler eliminates the UI-layer logic bugs that traditional React security tooling cannot catch because they're semantic, not syntactic. The Worker eliminates server-side exposure. Xano eliminates direct data access. Webflow's extension sandbox eliminates cross-site interference. Together, they create a defense-in-depth stack where a vulnerability in one layer cannot cascade.

7. Supply Chain Trust Partner Risk — Design over Configuration

7.1 The Supply Chain Risk Landscape

Recent high-profile breaches (SolarWinds, Codecov, MOVEit, xz-utils, Polyfill.io, 3CX) share a common pattern: trust in a third-party dependency or partner became the attack vector. Organizations with large partner ecosystems — e-commerce brands connected to CDPs, payment processors, analytics platforms, and marketing automation tools — face compounding supply chain risk. Every partner integration is a trust boundary. Every API credential stored is a potential compromise vector. Every unaudited data flow is a compliance liability.

Traditional configuration-heavy approaches amplify this risk:

7.2 Why Distributed Code + Design Simplicity Closes the Gap

CRM Sync's architecture is intentionally minimal at each layer:

┌────────────────────────────────────────────────────────────────┐
│                  SIMPLIFIED DISTRIBUTED CODE                    │
│                                                                │
│  Extension (React Compiler)                                    │
│  └─ Zero runtime deps in bundle                               │
│  └─ Compile-time validation = no runtime surprise              │
│  └─ Sandboxed in Webflow Designer = no cross-origin access     │
│                                                                │
│  Worker (Cloudflare, single file)                              │
│  └─ Zero npm runtime dependencies                              │
│  └─ No node_modules in production                              │
│  └─ No origin server = no server to patch                      │
│  └─ V8 isolate = no shared memory between requests             │
│                                                                │
│  Data (Xano)                                                   │
│  └─ No direct SQL access from any client                       │
│  └─ API-only with auth on every endpoint                       │
│  └─ Schema enforced at the platform level                      │
│                                                                │
│  Gateway (Webflow / Shopify)                                   │
│  └─ OAuth tokens scoped to minimum required permissions        │
│  └─ Webhook verification (HMAC / state nonce)                  │
│  └─ Platform-managed TLS and DDoS protection                   │
└────────────────────────────────────────────────────────────────┘

Design over configuration means the system's security properties are structural, not configurable. You cannot misconfigure the Worker into accepting unsigned webhooks — the HMAC check is compiled into the handler. You cannot accidentally expose PII to GA4 — the SHA-256 hash is in the code path, not a config toggle. You cannot bypass consent — the consent check is in the push function, not a flag you can turn off.

7.3 Supply Chain Trust Partner Risk Matrix

For each trust partner in the CRM Sync ecosystem, here is the specific risk and how the architecture mitigates it:

7.4 Design Principles for Partner Risk Reduction

Principle 1: No Transitive Trust

Every partner integration is direct — the Worker talks to Shopify's API, not through a third-party SDK that wraps Shopify's API. This eliminates transitive dependency risk. The Worker uses fetch() (built into the runtime) and crypto.subtle (Web Crypto API, built into V8). No axios, no node-fetch, no lodash, no moment.

Traditional:  App → SDK → HTTP lib → TLS lib → Partner API
              ↑       ↑        ↑         ↑
              4 supply chain trust points

CRM Sync:    Worker → fetch() → Partner API
              ↑
              0 third-party trust points in the runtime path

Principle 2: Credential Blast Radius = 1 Tenant

A compromised credential in a traditional multi-tenant system with shared env vars affects all tenants. In CRM Sync, every credential lives in tenant:{shop}:config. Compromising one tenant's Shopify token gives access to one shop's customer data — not all shops. The attacker must breach KV access + know the specific tenant key + bypass bearer token auth on the config endpoint.

Principle 3: Design-Time Enforcement > Runtime Configuration

Principle 4: On-Demand Development Reduces Exposure Window

Configuration-on-demand (traditional) means partners are always connected, always have valid credentials, always have access — even when no sync is running. Design-on-demand (CRM Sync) means:

• Feature-flagged streams: salesforce_enabled: false means the Salesforce credential is never read from config, the push function is never called, and no network request is made. The integration exists in code but is inert.
• Short-lived tokens: Adobe IMS tokens are cached with TTL and re-fetched on demand. Shopify tokens auto-refresh. OAuth state nonces expire in 10 minutes. There is no long-lived session to hijack.
• Cron-driven sync: Customer sync runs every 15 minutes via cron. Between syncs, no persistent connection exists to any partner API. The attack surface is intermittent, not continuous.

7.5 Organizational Impact

For organizations evaluating CRM Sync against traditional integration platforms:

The architecture is designed so that a compliance officer or security auditor can answer three questions in under 5 minutes:

1. "Where are credentials stored?" → tenant:{shop}:config in Cloudflare KV, encrypted at rest, masked in API responses.
2. "Where does customer data go?" → Only to streams where {stream}_enabled = true AND user consent is granted. Every push is logged to {stream}_sync_log.
3. "What happens if a partner is compromised?" → Set {stream}_enabled: false via POST /config. Credential is never read again. No code change, no redeploy, < 30 seconds.

8. Tool Architecture — Client-Side, Compile-Time & Dynamic Server

CRM Sync's stack divides cleanly into three execution phases. Each phase has distinct tools, and the security/trust guarantees differ at each phase. Understanding which tool operates where — and what it can and cannot do — is essential for both development and auditing.

8.1 Phase Map

┌─────────────────────────────────────────────────────────────────────┐
│  CLIENT SIDE (Browser / Webflow Designer)                           │
│  Runs: in user's browser or Webflow Designer sandbox                │
│  Trust: untrusted — all input must be validated server-side         │
│                                                                     │
│  Tools:                                                             │
│  ├─ Webflow Components (Designer Extensions UI)                     │
│  ├─ Webflow Semantic Design (styles, variables, classes)            │
│  ├─ Webflow Publish APIs (site publish, CMS push)                   │
│  ├─ Consent banner + DataLayer (gtag consent_mode v2)               │
│  ├─ Embed scripts (UCP dashboard, footer, compliance page)          │
│  ├─ Installable PWA (/configure shell + manifest + service worker)  │
│  └─ Cross-device event bus (crm-events.js → GTM / GA4 / Merchant)   │
├─────────────────────────────────────────────────────────────────────┤
│  COMPILE TIME (Build / CI)                                          │
│  Runs: developer machine or CI pipeline, before deploy              │
│  Trust: verified — output is the production artifact                │
│                                                                     │
│  Tools:                                                             │
│  ├─ TypeScript Compiler (tsc — type checking)                       │
│  ├─ React Compiler (automatic memoization, semantic validation)     │
│  ├─ Wrangler (Cloudflare Workers build + deploy)                    │
│  ├─ Webflow Extension Bundler (webflow extension bundle)            │
│  ├─ Compliance Harness (tests/compliance-harness.ts)                │
│  └─ Capacitor + Electron (native build — iOS / Android / desktop)   │
├─────────────────────────────────────────────────────────────────────┤
│  DYNAMIC SERVER (Edge Runtime / API)                                │
│  Runs: Cloudflare Workers V8 isolate or Xano API runtime            │
│  Trust: trusted — authenticated, isolated, encrypted                │
│                                                                     │
│  Tools:                                                             │
│  ├─ Cloudflare Workers (request handling, routing, auth)            │
│  ├─ PWA shell + manifest + SW + /get + /crm-events.js + /edge/geo   │
│  ├─ Cloudflare KV (config storage, state, token cache)              │
│  ├─ Wrangler Secrets (ADMIN_KEY, JWT_SECRET, API keys)              │
│  ├─ Xano Auth (user registration, login, JWT issuance)              │
│  ├─ Xano API (CRUD on storefront_users, consent_records, tags)      │
│  └─ Xano Functions (server-side logic, schema validation)           │
└─────────────────────────────────────────────────────────────────────┘

8.2 Client-Side Tools — Features & Functions

Webflow Components (Designer Extensions)

Webflow Semantic Design

Webflow Publish APIs

8.3 Compile-Time Tools — Features & Functions

TypeScript Compiler (tsc)

React Compiler

Wrangler (Cloudflare CLI)

Webflow Extension Bundler

8.4 Dynamic Server Tools — Features & Functions

Cloudflare Workers

Cloudflare KV

Wrangler Secrets

Xano Auth

Xano API

Xano Functions

8.5 Tool Interaction Matrix

How the three phases connect — which tool calls which, and what data crosses the boundary:

CLIENT SIDE                COMPILE TIME              DYNAMIC SERVER
─────────────              ────────────              ──────────────
Webflow Extension ──────────────────────────────────► Worker API
  (React UI)                                          (fetch handler)
       │                                                    │
       │  POST /config                                      │
       │  POST /sync/customers                              │
       │  GET /auth/me                                      ├──► KV (config)
       │                                                    ├──► Xano API (data)
       │                                                    ├──► Shopify Admin
Consent Banner ─────────────────────────────────────► Worker │      (GraphQL)
  (gtag + DataLayer)                                  /auth/ ├──► GA4 (MP v2)
       │                                          consent-  ├──► Adobe AEP
       │  consent_mode v2                           sync    ├──► Resend
       │  DataLayer push                                    └──► Webflow CMS
       │
       │                   TypeScript ───► Wrangler ──► Worker Deploy
       │                   React Compiler ──► Bundle ──► Webflow Upload
       │                   tsc ──► Type errors (build fails)
       │                   Compliance harness ──► Test results
       │
Webflow Publish ────────────────────────────────────► CDN (live site)
  (Designer UI)

8.6 Feature Gates by Execution Phase

9. Shopify/Google UCP — From product.csv to Server-Side

9.1 The CSV Era and Why It's Ending

For over a decade, the e-commerce data pipeline looked like this:

Shopify Admin → Export CSV → Edit in Excel/Sheets → Upload to Google Merchant Center
                                    ↓
                              Upload to CRM
                                    ↓
                              Upload to CDP
                                    ↓
                              Upload to consent platform

This worked when merchants had 50 products and 500 customers. It does not work when:

• Google requires real-time inventory and pricing (Merchant Center Next enforces server-side feeds)
• Shopify Customer Privacy API requires consent signals before data collection
• GA4 consent_mode v2 requires granular, real-time consent state (not a CSV column)
• GDPR Art. 17 (right to erasure) requires deletion propagated to all systems within 30 days — CSV workflows have no propagation mechanism
• Agentic AI needs machine-readable consent + entitlement state, not a spreadsheet

9.2 Shopify's Server-Side Shift

Shopify Customer Privacy API + UCP

Shopify's Customer Privacy API (shopify.customerPrivacy) is now the canonical consent interface for Shopify storefronts. Combined with the User Consent Preferences (UCP) model:

Shopify's Consent Signal Flow (Server-Side)

┌──────────────────────────────────────────────────────────────┐
│  STOREFRONT (Client)                                         │
│                                                              │
│  shopify.customerPrivacy.setTrackingConsent({                │
│    analytics: true/false,                                    │
│    marketing: true/false,                                    │
│    preferences: true/false,                                  │
│    sale_of_data: true/false      ← CCPA                     │
│  })                                                          │
│       │                                                      │
│       ▼                                                      │
│  Shopify passes consent to checkout + pixels                 │
│       │                                                      │
│       ▼                                                      │
│  CRM Sync Worker receives via:                               │
│  ├─ Webhook (customer-update with consent metafields)        │
│  ├─ POST /auth/consent-sync (embed context)                  │
│  └─ Cron sync (reads consent from Xano user_claims)          │
│       │                                                      │
│       ▼                                                      │
│  Worker enforces consent before pushing to:                  │
│  GA4 / Adobe AEP / Salesforce / Klaviyo / HubSpot / etc.    │
└──────────────────────────────────────────────────────────────┘

9.3 Google's Server-Side Shift

GA4 Measurement Protocol v2 + Consent Mode v2

Google's deprecation path is clear:

Page-View Conversion Schema → Event-Based Schema

This is the most impactful change for legacy apps that built around UA's page-view model:

UA (Legacy):
  Page View → Virtual Page View → Goal → Conversion
  /thank-you → pageview hit → destination goal → conversion counted

GA4 (Current):
  Event → Conversion Event → Key Event
  purchase → event with parameters → marked as key event → conversion counted

9.4 Impact on Legacy Applications

Matrixify (formerly Excelify)

What it does: Bulk import/export Shopify data via CSV/Excel — products, customers, orders, metafields.

Legacy risk:

Migration path: Replace Matrixify customer exports with GET /admin/shopify-customers (bearer-authed, returns current data from Shopify Admin API). Replace Matrixify customer imports with POST /sync/customers (validates, consent-checks, logs). Product CSV operations remain in Matrixify (CRM Sync does not manage product data — that's PIM Sync's domain).

Legacy CRMs (HubSpot CSV Import, Salesforce Data Loader, Zoho Import)

What they do: Bulk CSV import of customer records into CRM contact databases.

Legacy risk:

Migration path: Replace CSV imports with connected streams (Section 3). Each CRM gets:

1. Config fields in CrmSiteConfig (hubspot_enabled, hubspot_api_key, etc.)
2. A push{CRM}Event() function in the Worker
3. A {crm}_sync_log table in Xano
4. Consent gate in the push chain

OneTrust (and Legacy CMPs)

What it does: Cookie consent management platform. Manages consent banners, preference centers, and compliance reporting.

Legacy risk with CSV/page-view architecture:

Migration path: OneTrust (or any CMP) can coexist with CRM Sync. The CMP manages the UI banner; CRM Sync manages the server-side consent state:

OneTrust Banner (client)
  │
  ├─ Sets cookies (OneTrust's domain)
  ├─ Fires gtag('consent', 'update', {...})  ← GA4 consent_mode v2
  │
  └─ POST /auth/consent-sync (CRM Sync Worker)
       │
       ├─ Writes to user_claims (Xano — server-side truth)
       ├─ Writes to consent_records (Xano — audit log)
       └─ Maps CMP categories → GA4 signals → stream-specific consent

CRM Sync doesn't replace the CMP banner — it replaces the server-side consent enforcement that OneTrust doesn't provide. OneTrust tells the browser what's allowed. CRM Sync tells the server what's allowed.

Page-View Conversion Schema — What Dies

The page-view conversion schema affects every tool that reports on conversions:

9.5 The UCP Security/Privacy Model — Server-Side Consent as Infrastructure

Why Server-Side Consent Changes Everything

In the CSV/page-view era, consent was a client-side suggestion. The browser said "user consented to analytics" and every downstream system trusted that signal. But:

1. Client-side consent can be spoofed. A browser extension, ad blocker, or malicious script can forge consent signals. Server-side consent verification (checking user_claims in Xano) cannot be spoofed by the client.

1. Client-side consent doesn't persist. User clears cookies → consent state is lost → system defaults to either "re-ask" (friction) or "assume granted" (illegal under GDPR). Server-side consent in Xano persists indefinitely, tied to the authenticated user identity.

1. Client-side consent can't propagate. OneTrust sets a cookie. How does Salesforce know about it? CSV export? Manual sync? CRM Sync propagates consent changes to all connected streams within the same request cycle — consent change → check all streams → push updates → log results.

1. Client-side consent isn't auditable for agents. An AI agent processing a payment needs to verify: "Does this user consent to marketing data processing?" A cookie is not an API. GET /auth/me returns machine-readable consent state from Xano — the agent can make a provable decision.

UCP Privacy Guarantees (Server-Side)

9.6 Legacy App Migration Decision Matrix

For organizations evaluating which legacy tools to replace vs. keep:

9.7 Timeline Pressure

Organizations still using CSV workflows for customer data are accumulating compliance debt with each passing month. The page-view conversion schema is already dead — UA stopped processing in July 2024. The question is not whether to migrate, but how much historical data and process debt to carry forward.

10. Shopify App Pivot — Partner Dashboard → Dev Dashboard

10.1 What Changed and Why

Shopify has been migrating app management from the Partner Dashboard (partners.shopify.com) to the Dev Dashboard (dev.shopify.com). This is not a cosmetic rebrand — it reflects fundamental changes to how apps are created, configured, authenticated, and reviewed. Apps built against the old Partner Dashboard patterns will fail submission under the new requirements.

PARTNER DASHBOARD (Legacy)                DEV DASHBOARD (Current)
─────────────────────────                 ─────────────────────
App created in web UI                     App created via CLI or dev.shopify.com
Scopes configured in dashboard            Scopes declared in shopify.app.toml
Redirect URLs in dashboard form           redirect_urls in [auth] config
Extensions managed in dashboard           Extensions managed via CLI
OAuth: non-expiring offline tokens        OAuth: expiring tokens (60-min access, 90-day refresh)
GDPR webhooks: optional checkbox          GDPR webhooks: mandatory compliance_topics
API version: implicit                     API version: explicit in webhooks.api_version
Review: manual, opaque timeline           Review: AI-assisted self-review + structured submission
Protected customer data: blanket scopes   Protected customer data: field-level access requests
Billing: REST API                         Billing: GraphQL API (App Subscription)

10.2 Critical Pivot Changes

A. Authentication — Expiring Tokens (Mandatory since April 1, 2026)

Partner Dashboard era: Apps received non-expiring offline access tokens (shpat_*). Store the token once, use forever.

Dev Dashboard era: New public apps MUST use expiring tokens:

• Access token (shpua_*): 60-minute lifetime
• Refresh token (shprt_*): 90-day lifetime
• Token exchange must send expiring=1 parameter
• App must refresh proactively (before expiry, not after 401)
• Both access_token and refresh_token update on every refresh

B. Protected Customer Data — Field-Level Access

Partner Dashboard era: Request read_customers scope → get all customer fields.

Dev Dashboard era: Three access levels with field-level granularity:

CRM Sync impact: CRM Sync requires Level 1 minimum (read_customer_name, read_customer_email) for identity resolution. Level 2 if syncing phone/address to CDPs.

C. Configuration as Code — shopify.app.toml

Partner Dashboard era: App config in web forms. No version control. No diffing. No PR review.

Dev Dashboard era: shopify.app.toml is the single source of truth:

# shopify.app.toml — version-controlled, PR-reviewable, diffable
name = "CRM Sync"
client_id = "0e57977712f8a9d270a602848ff95308"
application_url = "https://hx-crm-sync.yoonsunlee150.workers.dev"
embedded = true

[auth]
redirect_urls = [
  "https://hx-crm-sync.yoonsunlee150.workers.dev/auth/callback"
]

[webhooks]
api_version = "2026-07"

[compliance_webhooks]
customer_deletion_url = "https://hx-crm-sync.yoonsunlee150.workers.dev/gdpr/customer-redact"
customer_data_request_url = "https://hx-crm-sync.yoonsunlee150.workers.dev/gdpr/data-request"
shop_deletion_url = "https://hx-crm-sync.yoonsunlee150.workers.dev/gdpr/shop-redact"

[access_scopes]
scopes = "read_customers,write_customers,read_orders"
use_legacy_install_flow = false

D. Extensions — CLI-Managed, Not Dashboard-Managed

Partner Dashboard era: Extensions created and configured in web UI. Bundle uploaded manually.

Dev Dashboard era: Extensions managed via Shopify CLI:

shopify app generate extension     # Create extension scaffold
shopify app dev                    # Local development server
shopify app deploy                 # Deploy extensions + update config

E. GDPR Compliance Webhooks — Mandatory

Partner Dashboard era: GDPR webhooks were an opt-in checkbox. Many apps never implemented them.

Dev Dashboard era: compliance_topics must be declared. Handlers must:

CRM Sync status: All three handlers implemented with HMAC verification (see Security Audit, routes #43-45).

F. Billing — GraphQL AppSubscription API

Partner Dashboard era: REST Billing API. Simple recurring charges.

Dev Dashboard era: GraphQL appSubscriptionCreate mutation with:

G. App Review — AI Self-Review + Structured Submission

Partner Dashboard era: Submit app → wait weeks → opaque feedback.

Dev Dashboard era (April 2026+):

1. AI-assisted self-review flags common issues before submission
2. Structured submission form with specific sections for each requirement
3. Test credentials must be provided and functional
4. Demo screencast required (English or English subtitles)
5. Emergency contact (email + phone) required

10.3 CRM Sync — Current Compliance Status

10.4 Downloadable Markdown Checklist

The full Shopify App pivot checklist is available as a standalone markdown file for download and tracking:

File: docs/shopify-app-checklist.llm.md

This file can be:

1. Fed to any LLM (Claude, GPT, Gemini) along with the codebase for automated compliance audit
2. Used as a PR checklist — paste into a GitHub PR description for team review
3. Tracked in project management — each numbered item maps to a task

Quick Reference — Checklist Sections

Key Dates

Download & Use

# Download the checklist
curl -O https://raw.githubusercontent.com/persephonepunch/crm-sync/master/docs/shopify-app-checklist.llm.md

# Feed to Claude for automated audit
cat shopify-app-checklist.llm.md src/index.ts | claude "Audit this app against the checklist"

# Or use as a GitHub PR template
cat shopify-app-checklist.llm.md >> .github/PULL_REQUEST_TEMPLATE/app-submission.md

10.5 Partner Dashboard → Dev Dashboard Migration Checklist

For apps migrating from Partner Dashboard to Dev Dashboard:

• Create app in Dev Dashboard (dev.shopify.com) or migrate existing app
• Generate shopify.app.toml via shopify app config push or create manually
• Move scopes from dashboard form to [access_scopes] in toml
• Move redirect URLs from dashboard form to [auth].redirect_urls in toml
• Implement expiring tokens — replace shpat_* with shpua_* + shprt_* flow
• Add proactive token refresh — check expiry before every API call
• Implement all three GDPR webhooks — data request, customer redact, shop redact
• Add HMAC validation to all webhook handlers
• Declare compliance_webhooks in toml
• Request protected customer data access in Partner Dashboard (Level 1 or 2)
• Test on non-dev store — dev stores bypass field-level scoping
• Handle null fields — unapproved/redacted fields return null
• Switch billing to GraphQL appSubscriptionCreate mutation
• Remove test: true from billing before submission
• Install Shopify CLI >= 3.84.1 — npm install -g @shopify/cli
• Move extensions to CLI management — shopify app generate extension
• Deploy via CLI — shopify app deploy (not dashboard upload)
• Set use_legacy_install_flow = false in toml
• Set webhooks.api_version to current supported version (2025-04+)
• Create app listing — icon, screenshots, demo video, test credentials
• Add emergency contact — email + phone
• Create privacy policy — link from app listing
• Run AI self-review — fix flagged issues before human review
• Verify Chrome incognito — app works without existing cookies/sessions

11. Architecture Comparison — Distributed Decentralized Build vs. Monolithic SSR

11.1 The Two Architectures

This section compares two complete application architectures for building authenticated, multi-tenant SaaS products that handle customer PII, consent state, and payment entitlements:

Architecture A (CRM Sync — Distributed Decentralized Build): Webflow/TypeScript/Vite Components + Cloudflare Workers/Functions + Xano API + TLS Auth

Architecture B (Conventional Full-Stack — Monolithic SSR): Next.js RSC + Prisma/Drizzle ORM + File System API + CSR/SSR Hydration

ARCHITECTURE A (Distributed)              ARCHITECTURE B (Monolithic)
──────────────────────────────             ─────────────────────────────
UI:     Webflow Components (Vite)          UI:     Next.js React Server Components
Logic:  Cloudflare Workers (V8 isolate)    Logic:  Next.js API routes + Server Actions
Data:   Xano API (managed PostgreSQL)      Data:   Prisma/Drizzle → self-managed DB
Auth:   Worker JWT + OAuth + HMAC + TLS    Auth:   NextAuth/Auth.js + session cookies
State:  Cloudflare KV (encrypted)          State:  File system / Redis / DB sessions
Deploy: Wrangler (edge, immutable)         Deploy: Vercel/Node (origin, mutable)
Deps:   0 runtime npm packages            Deps:   200-800+ npm packages

11.2 Layer-by-Layer Comparison

UI Layer: Webflow/Vite Components vs. Next.js RSC

Security implication: RSC introduces a new attack surface — the server/client component boundary. A "use server" directive that accidentally exposes a function allows direct invocation from the client. Webflow components run in a Designer sandbox with no server execution context — the boundary is physical (browser → Worker API), not a directive annotation.

Compute Layer: Cloudflare Workers vs. Next.js API Routes

Security implication: The Worker's restricted runtime is a security feature, not a limitation. No fs means no path traversal attacks. No child_process means no command injection. No shared memory means no cross-request data leaks. No eval() means no code injection. These attack classes are structurally impossible in the V8 isolate model — they don't need to be mitigated because they can't exist.

Data Layer: Xano API vs. Prisma/Drizzle ORM

Security implication: With Prisma/Drizzle, the application server has direct database credentials. A Server Action vulnerability, SSRF, or environment variable leak exposes the full connection string — and with it, SELECT * FROM users. With Xano, the application has an API key that only grants access to exposed API endpoints — not raw table access. The blast radius of a credential leak is fundamentally different:

Prisma credential leak:
  DATABASE_URL="postgresql://user:pass@host:5432/db"
  → Attacker: SELECT * FROM users; DROP TABLE consent_records;
  → Full read/write/delete on every table

Xano API key leak:
  XANO_API_KEY="xano_abc123"
  → Attacker: can call exposed API endpoints only
  → Cannot run arbitrary SQL
  → Cannot access tables without endpoints
  → Cannot DROP, ALTER, or TRUNCATE anything
  → Rate-limited by Xano

Auth Layer: Worker JWT + TLS vs. NextAuth/Auth.js

Security implication: NextAuth's flexibility is its risk. The adapter pattern means auth behavior depends on which database adapter, which session strategy, and which callback configuration the developer chose. Misconfiguration (leaving NEXTAUTH_SECRET as default, using jwt strategy with database adapter, forgetting to set secureCookie: true) creates vulnerabilities that static analysis can't catch because they're configuration errors, not code errors. The Worker's auth is code — it either verifies the HMAC or it doesn't. No configuration to misconfigure.

State Layer: Cloudflare KV vs. File System / Redis

Security implication: The File System API in Next.js/Node.js applications is a recurring source of vulnerabilities. Server Actions that accept file paths, image upload handlers that write to disk, cache files that store session data — all create path traversal and local file inclusion (LFI) attack surfaces. Cloudflare Workers have no file system — this entire category of vulnerability is eliminated by the runtime.

11.3 Hydration Security Risks

CSR/SSR Hydration — The Serialization Boundary Problem

Next.js RSC serializes component trees from server to client. This serialization is the most novel attack surface in modern React:

Server Component renders → RSC payload (JSON-like wire format) → Client deserializes → Hydration

Risk points:
1. Server Component accidentally includes server-only data in render output
2. RSC payload includes props that were meant for server-only children
3. Client Component receives hydration data that contains secrets/tokens
4. Hydration mismatch → client re-renders with different (potentially exposed) data

The "use server" Problem

Next.js Server Actions are functions annotated with "use server" that the client can invoke directly:

// Next.js Server Action — this becomes a POST endpoint automatically
"use server"
async function updateProfile(formData: FormData) {
  const email = formData.get("email");
  await db.user.update({ where: { id: session.userId }, data: { email } });
}

What can go wrong:

11.4 Dependency Chain Risk

npm Supply Chain — 0 vs. 800+

CRM SYNC (Architecture A)                NEXT.JS APP (Architecture B)
──────────────────────────                ────────────────────────────
Runtime deps: 0                           Runtime deps: 200-800+
                                          ├─ next (core)
Worker uses:                              ├─ react, react-dom
├─ fetch()        (V8 built-in)           ├─ @prisma/client (or drizzle-orm)
├─ crypto.subtle  (V8 built-in)           ├─ next-auth (+ adapters)
├─ Request/Response (V8 built-in)         ├─ zod (validation)
├─ URL, Headers   (V8 built-in)           ├─ bcrypt / argon2
├─ TextEncoder    (V8 built-in)           ├─ jsonwebtoken
├─ KV bindings    (Cloudflare runtime)    ├─ cookie / express-session
└─ (nothing else)                         ├─ @tanstack/query
                                          ├─ axios / ky
                                          ├─ ... (200+ transitive deps)
                                          └─ Each dep = supply chain trust point

11.5 Deployment Model Risk

11.6 Specific CVE Classes Eliminated by Distributed Architecture

11.7 Why Distributed Decentralized Build Resolves These Risks

The core insight is that a distributed, decentralized build doesn't just mitigate risks — it eliminates risk categories by removing the capabilities that make them possible:

┌────────────────────────────────────────────────────────────────────┐
│               MONOLITHIC SSR (Next.js + Prisma)                    │
│                                                                    │
│  Single Node.js process handles:                                   │
│  ├─ Rendering (RSC → HTML → hydration)                            │
│  ├─ API logic (Server Actions, API routes)                        │
│  ├─ Database queries (Prisma/Drizzle → SQL)                       │
│  ├─ Auth (NextAuth middleware)                                     │
│  ├─ File I/O (uploads, cache, sessions)                           │
│  ├─ Process execution (if needed)                                 │
│  └─ State (global vars, module scope)                             │
│                                                                    │
│  Compromise of ANY layer → access to ALL layers                   │
│  SSRF → reads DB credentials from process.env                     │
│  Server Action bug → arbitrary SQL via Prisma                     │
│  Path traversal → reads .env file from disk                       │
│  Prototype pollution → affects all concurrent requests            │
└────────────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────────────┐
│               DISTRIBUTED BUILD (Workers + Xano + Webflow)         │
│                                                                    │
│  Webflow Extension (UI only):                                      │
│  ├─ Renders components from compiled bundle                       │
│  ├─ Cannot access Worker secrets, Xano data, or file system       │
│  └─ Sandboxed in Webflow Designer iframe                          │
│                                                                    │
│  Cloudflare Worker (Logic only):                                   │
│  ├─ Routes requests, validates auth, enforces consent             │
│  ├─ Cannot access file system, processes, or raw sockets          │
│  ├─ Cannot run SQL (talks to Xano API, not database)              │
│  └─ V8 isolate — no shared state between requests                 │
│                                                                    │
│  Xano (Data only):                                                 │
│  ├─ Exposes API endpoints (not raw SQL)                           │
│  ├─ Validates schema at platform level                            │
│  ├─ Manages connections, backups, scaling                         │
│  └─ Cannot be reached except through authenticated API calls      │
│                                                                    │
│  Compromise of ONE layer → access to ONLY that layer              │
│  Worker SSRF → can call public APIs only (no internal network)    │
│  Xano API key leak → can call endpoints only (no raw SQL)         │
│  Extension compromise → can render UI only (no secrets, no data)  │
└────────────────────────────────────────────────────────────────────┘

The Blast Radius Difference

11.8 When Next.js RSC is the Right Choice

This comparison is not a universal recommendation against Next.js. Next.js RSC is better when:

CRM Sync's architecture is optimized for multi-tenant SaaS with PII, consent, and compliance requirements — where the blast radius of a single vulnerability can affect thousands of users across multiple systems. The distributed model pays a DX cost (three systems to coordinate) to buy a security property (physical isolation between layers) that no amount of Next.js middleware can replicate.

12. Success Criteria