Environment Variable Brand Neutralization Plan

Overview

This document outlines the migration strategy for PREGO_* environment variables to brand-neutral alternatives. Due to the high risk of breaking deployed systems, this migration requires careful planning and backward compatibility support.

Current State

High-Usage Variables (> 20 occurrences)

Current Name	Proposed Name	Category	Risk
PREGO_TRACE_ID_HEADER	TRACE_ID_HEADER	Observability	High
PREGO_CONTROL_PLANE_URL	CONTROL_PLANE_URL	Infrastructure	High
PREGO_JWT	AUTH_JWT	Auth Cookie	High
PREGO_LOCALE	LOCALE	i18n	Medium
PREGO_CONSENT_*	CONSENT_*	Privacy	Medium
PREGO_AUTH_URL	AUTH_URL	Infrastructure	High

Medium-Usage Variables (10-20 occurrences)

Current Name	Proposed Name	Category
PREGO_COOKIE_*	COOKIE_*	Cookie Names
PREGO_EID	EID	Event ID
PREGO_DEVICE_ID	DEVICE_ID	Tracking
PREGO_PENDING_EID	PENDING_EID	Event ID
PREGO_CONTROL_PLANE_INTERNAL_API_KEY	CP_INTERNAL_API_KEY	Auth

Low-Usage Variables (< 10 occurrences)

Current Name	Proposed Name	Category
PREGO_ONBOARDING_*	ONBOARDING_*	Onboarding
PREGO_DEMO_*	DEMO_*	Demo Mode
PREGO_SESSION	SESSION	Auth
PREGO_WWW_BASE_URL	WWW_BASE_URL	Infrastructure
PREGO_JWT_COOKIE_DOMAIN	JWT_COOKIE_DOMAIN	Auth
PREGO_ZUPLO_INTERNAL_API_KEY	ZUPLO_INTERNAL_API_KEY	Auth
PREGO_THEME	THEME	UI
PREGO_BILLING_PROXY_URL	BILLING_PROXY_URL	Infrastructure

Migration Strategy

Phase 1: Add Fallback Support (Low Risk)

For each environment variable, implement a fallback pattern:

// Before
const controlPlaneUrl = process.env.PREGO_CONTROL_PLANE_URL

// After
const controlPlaneUrl = process.env.CONTROL_PLANE_URL
  ?? process.env.PREGO_CONTROL_PLANE_URL

Implemented in @platform/env-utils (packages/env-utils):

import { getEnvWithFallback, COMMON_ENV_MAPPINGS } from '@platform/env-utils';

// Single variable
const controlPlaneUrl = getEnvWithFallback(
  process.env,
  'CONTROL_PLANE_URL',
  'PREGO_CONTROL_PLANE_URL'
);

// With deprecation warning
import { getEnvWithFallbackAndWarn } from '@platform/env-utils';
const url = getEnvWithFallbackAndWarn(env, 'CONTROL_PLANE_URL', 'PREGO_CONTROL_PLANE_URL');

// Batch resolution using pre-defined mappings
import { resolveEnvMappings, ADMIN_WEB_ENV_MAPPINGS } from '@platform/env-utils';
const resolved = resolveEnvMappings(process.env, ADMIN_WEB_ENV_MAPPINGS);

Phase 2: Update Infrastructure Variables

Order:

1. CONTROL_PLANE_URL (NEXT_PUBLIC_PREGO_CONTROL_PLANE_URL)
2. AUTH_URL (NEXT_PUBLIC_PREGO_AUTH_URL)
3. WWW_BASE_URL (PREGO_WWW_BASE_URL)

Procedure:

1. Deploy code with fallback support
2. Update Cloudflare Worker variables to new names
3. Monitor for errors
4. Remove legacy variable after 2 weeks

Phase 3: Update Cookie Names

Special consideration: Cookie names affect browser storage. Changing cookie names requires:

1. Migration script to copy old cookie → new cookie
2. Extended fallback period (reading both cookies)
3. Clear old cookies after migration window

Order:

1. JWT cookie (PREGO_JWT → AUTH_JWT)
2. LOCALE cookie (PREGO_LOCALE → LOCALE)
3. CONSENT cookie (PREGO_CONSENT → CONSENT)
4. THEME cookie (PREGO_THEME → THEME)

Phase 4: Update Client-Side Constants

Browser code changes require:

1. Version-coordinated deployment (www + client-web + admin-web simultaneously)
2. Cache invalidation for static assets

Phase 5: Remove Legacy Support

After migration window (recommended: 30 days minimum):

1. Remove fallback code
2. Delete legacy environment variables from Cloudflare
3. Update documentation

Implementation Checklist

• Create getEnvWithFallback utility — implemented in @platform/env-utils (packages/env-utils/src/index.ts)
• Add deprecation warnings when legacy names are used — warnLegacyEnvUsage() and getEnvWithFallbackAndWarn() in same package
• Define environment variable mappings — COMMON_ENV_MAPPINGS, app-specific mappings in packages/env-utils/src/mappings.ts
• Update @platform/cookies with fallback cookie reading (AUTH_JWT / PREGO_JWT — partial: see apps/admin-web/lib/cookie-header-for-zuplo-upstream.ts)
• Document new variable names in deployment guides
• Coordinate deployment timeline with operations team
• Monitor error rates during migration
• Adopt @platform/env-utils in apps (admin-web, client-web, www) and workers (control-plane)

Not Changing (HTTP Headers)

The following HTTP header constants will NOT change as they are part of the public API contract:

• X-Prego-Api-Key (client API key header)
• X-Prego-Agent-Key (agent API key header)
• X-Prego-Demo (demo mode header)
• X-Prego-M-Admin-Login (admin login gate)

These require API versioning and client update coordination, which is out of scope for this phase.

Risk Mitigation

1. Feature flags: Use feature flags to toggle new vs legacy names
2. Monitoring: Set up alerts for missing environment variables
3. Rollback plan: Document steps to revert to legacy names
4. Communication: Notify operations team 1 week before each phase

Timeline Estimate

Phase	Duration	Dependencies
Phase 1	1 week	None
Phase 2	2 weeks	Phase 1 complete
Phase 3	2 weeks	Phase 2 complete
Phase 4	1 week	Phase 3 complete
Phase 5	1 day	30 days after Phase 4

Total: ~6-8 weeks (excluding migration window)