@striae-org/striae 5.3.1 → 5.4.0

package/scripts/deploy-config/modules/scaffolding.sh

@@ -0,0 +1,310 @@
+#!/bin/bash
+
+copy_example_configs() {
+    echo -e "\n${BLUE}📋 Copying example configuration files...${NC}"
+
+    # Copy app configuration files
+    echo -e "${YELLOW}  Copying app configuration files...${NC}"
+
+    # Copy app config-example directory to config (always sync non-admin files)
+    if [ -d "app/config-example" ]; then
+        local admin_service_backup=""
+        local copied_config_files=0
+        local skipped_existing_files=0
+
+        if [ -f "app/config/admin-service.json" ]; then
+            admin_service_backup=$(mktemp)
+            cp "app/config/admin-service.json" "$admin_service_backup"
+        fi
+
+        if [ "$update_env" = "true" ]; then
+            rm -rf app/config
+        fi
+
+        mkdir -p app/config
+
+        while IFS= read -r source_file; do
+            local relative_path
+            local destination_file
+            relative_path="${source_file#app/config-example/}"
+            destination_file="app/config/$relative_path"
+
+            mkdir -p "$(dirname "$destination_file")"
+
+            if [ "$update_env" = "true" ] || [ ! -f "$destination_file" ]; then
+                cp "$source_file" "$destination_file"
+                copied_config_files=$((copied_config_files + 1))
+            else
+                skipped_existing_files=$((skipped_existing_files + 1))
+            fi
+        done < <(find app/config-example -type f ! -name "admin-service.json")
+
+        # Ensure example credentials are never copied from config-example.
+        rm -f app/config/admin-service.json
+
+        if [ -n "$admin_service_backup" ] && [ -f "$admin_service_backup" ]; then
+            cp "$admin_service_backup" "app/config/admin-service.json"
+            rm -f "$admin_service_backup"
+            echo -e "${GREEN}    ✅ app: preserved existing admin-service.json${NC}"
+        else
+            echo -e "${YELLOW}    ⚠️  app: skipped copying admin-service.json (provide your own credentials file)${NC}"
+        fi
+
+        if [ "$update_env" = "true" ]; then
+            echo -e "${GREEN}    ✅ app: config directory reset from config-example (excluding admin-service.json)${NC}"
+        else
+            echo -e "${GREEN}    ✅ app: synced missing files from config-example (excluding admin-service.json)${NC}"
+        fi
+
+        if [ "$skipped_existing_files" -gt 0 ]; then
+            echo -e "${YELLOW}    ℹ️  app: kept $skipped_existing_files existing config file(s)${NC}"
+        fi
+
+        echo -e "${GREEN}    ✅ app: copied $copied_config_files config file(s) from config-example${NC}"
+    fi
+
+    # Copy auth route template files
+    echo -e "${YELLOW}  Copying auth route template files...${NC}"
+
+    if [ -f "app/routes/auth/login.example.tsx" ] && { [ "$update_env" = "true" ] || [ ! -f "app/routes/auth/login.tsx" ]; }; then
+        cp app/routes/auth/login.example.tsx app/routes/auth/login.tsx
+        echo -e "${GREEN}    ✅ auth: login.tsx created from example${NC}"
+    elif [ -f "app/routes/auth/login.tsx" ]; then
+        echo -e "${YELLOW}    ⚠️  auth: login.tsx already exists, skipping copy${NC}"
+    fi
+
+    if [ -f "app/routes/auth/login.module.example.css" ] && { [ "$update_env" = "true" ] || [ ! -f "app/routes/auth/login.module.css" ]; }; then
+        cp app/routes/auth/login.module.example.css app/routes/auth/login.module.css
+        echo -e "${GREEN}    ✅ auth: login.module.css created from example${NC}"
+    elif [ -f "app/routes/auth/login.module.css" ]; then
+        echo -e "${YELLOW}    ⚠️  auth: login.module.css already exists, skipping copy${NC}"
+    fi
+
+    # Navigate to each worker directory and copy the example file
+    echo -e "${YELLOW}  Copying worker configuration files...${NC}"
+
+    cd workers/user-worker
+    if [ -f "wrangler.jsonc.example" ] && { [ "$update_env" = "true" ] || [ ! -f "wrangler.jsonc" ]; }; then
+        cp wrangler.jsonc.example wrangler.jsonc
+        echo -e "${GREEN}    ✅ user-worker: wrangler.jsonc created from example${NC}"
+    elif [ -f "wrangler.jsonc" ]; then
+        echo -e "${YELLOW}    ⚠️  user-worker: wrangler.jsonc already exists, skipping copy${NC}"
+    fi
+
+    cd ../data-worker
+    if [ -f "wrangler.jsonc.example" ] && { [ "$update_env" = "true" ] || [ ! -f "wrangler.jsonc" ]; }; then
+        cp wrangler.jsonc.example wrangler.jsonc
+        echo -e "${GREEN}    ✅ data-worker: wrangler.jsonc created from example${NC}"
+    elif [ -f "wrangler.jsonc" ]; then
+        echo -e "${YELLOW}    ⚠️  data-worker: wrangler.jsonc already exists, skipping copy${NC}"
+    fi
+
+    cd ../audit-worker
+    if [ -f "wrangler.jsonc.example" ] && { [ "$update_env" = "true" ] || [ ! -f "wrangler.jsonc" ]; }; then
+        cp wrangler.jsonc.example wrangler.jsonc
+        echo -e "${GREEN}    ✅ audit-worker: wrangler.jsonc created from example${NC}"
+    elif [ -f "wrangler.jsonc" ]; then
+        echo -e "${YELLOW}    ⚠️  audit-worker: wrangler.jsonc already exists, skipping copy${NC}"
+    fi
+
+    cd ../image-worker
+    if [ -f "wrangler.jsonc.example" ] && { [ "$update_env" = "true" ] || [ ! -f "wrangler.jsonc" ]; }; then
+        cp wrangler.jsonc.example wrangler.jsonc
+        echo -e "${GREEN}    ✅ image-worker: wrangler.jsonc created from example${NC}"
+    elif [ -f "wrangler.jsonc" ]; then
+        echo -e "${YELLOW}    ⚠️  image-worker: wrangler.jsonc already exists, skipping copy${NC}"
+    fi
+
+    cd ../pdf-worker
+    if [ -f "wrangler.jsonc.example" ] && { [ "$update_env" = "true" ] || [ ! -f "wrangler.jsonc" ]; }; then
+        cp wrangler.jsonc.example wrangler.jsonc
+        echo -e "${GREEN}    ✅ pdf-worker: wrangler.jsonc created from example${NC}"
+    elif [ -f "wrangler.jsonc" ]; then
+        echo -e "${YELLOW}    ⚠️  pdf-worker: wrangler.jsonc already exists, skipping copy${NC}"
+    fi
+
+    # Return to project root
+    cd ../..
+
+    # Copy worker source template files
+    echo -e "${YELLOW}  Copying worker source template files...${NC}"
+
+    if [ -f "workers/user-worker/src/user-worker.example.ts" ] && { [ "$update_env" = "true" ] || [ ! -f "workers/user-worker/src/user-worker.ts" ]; }; then
+        cp workers/user-worker/src/user-worker.example.ts workers/user-worker/src/user-worker.ts
+        echo -e "${GREEN}    ✅ user-worker: user-worker.ts created from example${NC}"
+    elif [ -f "workers/user-worker/src/user-worker.ts" ]; then
+        echo -e "${YELLOW}    ⚠️  user-worker: user-worker.ts already exists, skipping copy${NC}"
+    fi
+
+    if [ -f "workers/data-worker/src/data-worker.example.ts" ] && { [ "$update_env" = "true" ] || [ ! -f "workers/data-worker/src/data-worker.ts" ]; }; then
+        cp workers/data-worker/src/data-worker.example.ts workers/data-worker/src/data-worker.ts
+        echo -e "${GREEN}    ✅ data-worker: data-worker.ts created from example${NC}"
+    elif [ -f "workers/data-worker/src/data-worker.ts" ]; then
+        echo -e "${YELLOW}    ⚠️  data-worker: data-worker.ts already exists, skipping copy${NC}"
+    fi
+
+    if [ -f "workers/audit-worker/src/audit-worker.example.ts" ] && { [ "$update_env" = "true" ] || [ ! -f "workers/audit-worker/src/audit-worker.ts" ]; }; then
+        cp workers/audit-worker/src/audit-worker.example.ts workers/audit-worker/src/audit-worker.ts
+        echo -e "${GREEN}    ✅ audit-worker: audit-worker.ts created from example${NC}"
+    elif [ -f "workers/audit-worker/src/audit-worker.ts" ]; then
+        echo -e "${YELLOW}    ⚠️  audit-worker: audit-worker.ts already exists, skipping copy${NC}"
+    fi
+
+    if [ -f "workers/image-worker/src/image-worker.example.ts" ] && { [ "$update_env" = "true" ] || [ ! -f "workers/image-worker/src/image-worker.ts" ]; }; then
+        cp workers/image-worker/src/image-worker.example.ts workers/image-worker/src/image-worker.ts
+        echo -e "${GREEN}    ✅ image-worker: image-worker.ts created from example${NC}"
+    elif [ -f "workers/image-worker/src/image-worker.ts" ]; then
+        echo -e "${YELLOW}    ⚠️  image-worker: image-worker.ts already exists, skipping copy${NC}"
+    fi
+
+    if [ -f "workers/pdf-worker/src/pdf-worker.example.ts" ] && { [ "$update_env" = "true" ] || [ ! -f "workers/pdf-worker/src/pdf-worker.ts" ]; }; then
+        cp workers/pdf-worker/src/pdf-worker.example.ts workers/pdf-worker/src/pdf-worker.ts
+        echo -e "${GREEN}    ✅ pdf-worker: pdf-worker.ts created from example${NC}"
+    elif [ -f "workers/pdf-worker/src/pdf-worker.ts" ]; then
+        echo -e "${YELLOW}    ⚠️  pdf-worker: pdf-worker.ts already exists, skipping copy${NC}"
+    fi
+
+    # Copy main wrangler.toml from example
+    if [ -f "wrangler.toml.example" ] && { [ "$update_env" = "true" ] || [ ! -f "wrangler.toml" ]; }; then
+        cp wrangler.toml.example wrangler.toml
+        echo -e "${GREEN}    ✅ root: wrangler.toml created from example${NC}"
+    elif [ -f "wrangler.toml" ]; then
+        echo -e "${YELLOW}    ⚠️  root: wrangler.toml already exists, skipping copy${NC}"
+    fi
+
+    echo -e "${GREEN}✅ Configuration file copying completed${NC}"
+}
+
+update_wrangler_configs() {
+    echo -e "\n${BLUE}🔧 Updating wrangler configuration files...${NC}"
+
+    local normalized_account_id
+    local escaped_account_id
+    local normalized_pages_custom_domain
+    local escaped_pages_custom_domain
+
+    normalized_account_id=$(printf '%s' "$ACCOUNT_ID" | tr -d '\r' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+    ACCOUNT_ID="$normalized_account_id"
+    export ACCOUNT_ID
+    write_env_var "ACCOUNT_ID" "$ACCOUNT_ID"
+    escaped_account_id=$(escape_for_sed_replacement "$ACCOUNT_ID")
+
+    normalized_pages_custom_domain=$(normalize_domain_value "$PAGES_CUSTOM_DOMAIN")
+    PAGES_CUSTOM_DOMAIN="$normalized_pages_custom_domain"
+    export PAGES_CUSTOM_DOMAIN
+    write_env_var "PAGES_CUSTOM_DOMAIN" "$PAGES_CUSTOM_DOMAIN"
+    escaped_pages_custom_domain=$(escape_for_sed_replacement "$PAGES_CUSTOM_DOMAIN")
+
+    # Audit Worker
+    if [ -f "workers/audit-worker/wrangler.jsonc" ]; then
+        echo -e "${YELLOW}  Updating audit-worker/wrangler.jsonc...${NC}"
+        sed -i "s/\"AUDIT_WORKER_NAME\"/\"$AUDIT_WORKER_NAME\"/g" workers/audit-worker/wrangler.jsonc
+        sed -i "s/\"ACCOUNT_ID\"/\"$escaped_account_id\"/g" workers/audit-worker/wrangler.jsonc
+        sed -i "s/\"AUDIT_BUCKET_NAME\"/\"$AUDIT_BUCKET_NAME\"/g" workers/audit-worker/wrangler.jsonc
+        echo -e "${GREEN}    ✅ audit-worker configuration updated${NC}"
+    fi
+
+    if [ -f "workers/audit-worker/src/audit-worker.ts" ]; then
+        echo -e "${YELLOW}  Updating audit-worker source placeholders...${NC}"
+        sed -i "s|'Access-Control-Allow-Origin': '[^']*'|'Access-Control-Allow-Origin': 'https://$escaped_pages_custom_domain'|g" workers/audit-worker/src/audit-worker.ts
+        echo -e "${GREEN}    ✅ audit-worker source placeholders updated${NC}"
+    fi
+
+    if [ -f "workers/data-worker/wrangler.jsonc" ]; then
+        echo -e "${YELLOW}  Updating data-worker/wrangler.jsonc...${NC}"
+        sed -i "s/\"DATA_WORKER_NAME\"/\"$DATA_WORKER_NAME\"/g" workers/data-worker/wrangler.jsonc
+        sed -i "s/\"ACCOUNT_ID\"/\"$escaped_account_id\"/g" workers/data-worker/wrangler.jsonc
+        sed -i "s/\"DATA_BUCKET_NAME\"/\"$DATA_BUCKET_NAME\"/g" workers/data-worker/wrangler.jsonc
+        echo -e "${GREEN}    ✅ data-worker configuration updated${NC}"
+    fi
+
+    if [ -f "workers/data-worker/src/data-worker.ts" ]; then
+        echo -e "${YELLOW}  Updating data-worker source placeholders...${NC}"
+        sed -i "s|'Access-Control-Allow-Origin': '[^']*'|'Access-Control-Allow-Origin': 'https://$escaped_pages_custom_domain'|g" workers/data-worker/src/data-worker.ts
+        echo -e "${GREEN}    ✅ data-worker source placeholders updated${NC}"
+    fi
+
+    if [ -f "workers/image-worker/wrangler.jsonc" ]; then
+        echo -e "${YELLOW}  Updating image-worker/wrangler.jsonc...${NC}"
+        sed -i "s/\"IMAGES_WORKER_NAME\"/\"$IMAGES_WORKER_NAME\"/g" workers/image-worker/wrangler.jsonc
+        sed -i "s/\"ACCOUNT_ID\"/\"$escaped_account_id\"/g" workers/image-worker/wrangler.jsonc
+        sed -i "s/\"FILES_BUCKET_NAME\"/\"$FILES_BUCKET_NAME\"/g" workers/image-worker/wrangler.jsonc
+        echo -e "${GREEN}    ✅ image-worker configuration updated${NC}"
+    fi
+
+    if [ -f "workers/image-worker/src/image-worker.ts" ]; then
+        echo -e "${YELLOW}  Updating image-worker source placeholders...${NC}"
+        sed -i "s|'Access-Control-Allow-Origin': '[^']*'|'Access-Control-Allow-Origin': 'https://$escaped_pages_custom_domain'|g" workers/image-worker/src/image-worker.ts
+        echo -e "${GREEN}    ✅ image-worker source placeholders updated${NC}"
+    fi
+
+    if [ -f "workers/pdf-worker/wrangler.jsonc" ]; then
+        echo -e "${YELLOW}  Updating pdf-worker/wrangler.jsonc...${NC}"
+        sed -i "s/\"PDF_WORKER_NAME\"/\"$PDF_WORKER_NAME\"/g" workers/pdf-worker/wrangler.jsonc
+        sed -i "s/\"ACCOUNT_ID\"/\"$escaped_account_id\"/g" workers/pdf-worker/wrangler.jsonc
+        echo -e "${GREEN}    ✅ pdf-worker configuration updated${NC}"
+    fi
+
+    if [ -f "workers/pdf-worker/src/pdf-worker.ts" ]; then
+        echo -e "${YELLOW}  Updating pdf-worker source placeholders...${NC}"
+        sed -i "s|'Access-Control-Allow-Origin': '[^']*'|'Access-Control-Allow-Origin': 'https://$escaped_pages_custom_domain'|g" workers/pdf-worker/src/pdf-worker.ts
+        echo -e "${GREEN}    ✅ pdf-worker source placeholders updated${NC}"
+    fi
+
+    if [ -f "workers/user-worker/wrangler.jsonc" ]; then
+        echo -e "${YELLOW}  Updating user-worker/wrangler.jsonc...${NC}"
+        sed -i "s/\"USER_WORKER_NAME\"/\"$USER_WORKER_NAME\"/g" workers/user-worker/wrangler.jsonc
+        sed -i "s/\"ACCOUNT_ID\"/\"$escaped_account_id\"/g" workers/user-worker/wrangler.jsonc
+        sed -i "s/\"KV_STORE_ID\"/\"$KV_STORE_ID\"/g" workers/user-worker/wrangler.jsonc
+        sed -i "s/\"DATA_BUCKET_NAME\"/\"$DATA_BUCKET_NAME\"/g" workers/user-worker/wrangler.jsonc
+        sed -i "s/\"FILES_BUCKET_NAME\"/\"$FILES_BUCKET_NAME\"/g" workers/user-worker/wrangler.jsonc
+        echo -e "${GREEN}    ✅ user-worker configuration updated${NC}"
+    fi
+
+    if [ -f "workers/user-worker/src/user-worker.ts" ]; then
+        echo -e "${YELLOW}  Updating user-worker source placeholders...${NC}"
+        sed -i "s|'Access-Control-Allow-Origin': '[^']*'|'Access-Control-Allow-Origin': 'https://$escaped_pages_custom_domain'|g" workers/user-worker/src/user-worker.ts
+        echo -e "${GREEN}    ✅ user-worker source placeholders updated${NC}"
+    fi
+
+    if [ -f "wrangler.toml" ]; then
+        echo -e "${YELLOW}  Updating wrangler.toml...${NC}"
+        sed -i "s/\"PAGES_PROJECT_NAME\"/\"$PAGES_PROJECT_NAME\"/g" wrangler.toml
+        echo -e "${GREEN}    ✅ main wrangler.toml configuration updated${NC}"
+    fi
+
+    echo -e "${YELLOW}  Updating app configuration files...${NC}"
+
+    if [ -f "app/config/config.json" ]; then
+        echo -e "${YELLOW}    Updating app/config/config.json...${NC}"
+        local escaped_manifest_signing_key_id
+        local escaped_manifest_signing_public_key
+        local escaped_export_encryption_key_id
+        local escaped_export_encryption_public_key
+        escaped_manifest_signing_key_id=$(escape_for_sed_replacement "$MANIFEST_SIGNING_KEY_ID")
+        escaped_manifest_signing_public_key=$(escape_for_sed_replacement "$MANIFEST_SIGNING_PUBLIC_KEY")
+        escaped_export_encryption_key_id=$(escape_for_sed_replacement "$EXPORT_ENCRYPTION_KEY_ID")
+        escaped_export_encryption_public_key=$(escape_for_sed_replacement "$EXPORT_ENCRYPTION_PUBLIC_KEY")
+
+        sed -i "s|\"url\": \"[^\"]*\"|\"url\": \"https://$escaped_pages_custom_domain\"|g" app/config/config.json
+        sed -i "s|\"MANIFEST_SIGNING_KEY_ID\"|\"$escaped_manifest_signing_key_id\"|g" app/config/config.json
+        sed -i "s|\"MANIFEST_SIGNING_PUBLIC_KEY\"|\"$escaped_manifest_signing_public_key\"|g" app/config/config.json
+        sed -i "s|\"EXPORT_ENCRYPTION_KEY_ID\"|\"$escaped_export_encryption_key_id\"|g" app/config/config.json
+        sed -i "s|\"EXPORT_ENCRYPTION_PUBLIC_KEY\"|\"$escaped_export_encryption_public_key\"|g" app/config/config.json
+        echo -e "${GREEN}      ✅ app config.json updated${NC}"
+    fi
+
+    if [ -f "app/config/firebase.ts" ]; then
+        echo -e "${YELLOW}    Updating app/config/firebase.ts...${NC}"
+        sed -i "s|\"YOUR_FIREBASE_API_KEY\"|\"$API_KEY\"|g" app/config/firebase.ts
+        sed -i "s|\"YOUR_FIREBASE_AUTH_DOMAIN\"|\"$AUTH_DOMAIN\"|g" app/config/firebase.ts
+        sed -i "s|\"YOUR_FIREBASE_PROJECT_ID\"|\"$PROJECT_ID\"|g" app/config/firebase.ts
+        sed -i "s|\"YOUR_FIREBASE_STORAGE_BUCKET\"|\"$STORAGE_BUCKET\"|g" app/config/firebase.ts
+        sed -i "s|\"YOUR_FIREBASE_MESSAGING_SENDER_ID\"|\"$MESSAGING_SENDER_ID\"|g" app/config/firebase.ts
+        sed -i "s|\"YOUR_FIREBASE_APP_ID\"|\"$APP_ID\"|g" app/config/firebase.ts
+        sed -i "s|\"YOUR_FIREBASE_MEASUREMENT_ID\"|\"$MEASUREMENT_ID\"|g" app/config/firebase.ts
+        echo -e "${GREEN}      ✅ app firebase.ts updated${NC}"
+    fi
+
+    echo -e "${GREEN}✅ All configuration files updated${NC}"
+}

package/scripts/deploy-config/modules/validation.sh

@@ -0,0 +1,354 @@
+#!/bin/bash
+
+validate_data_at_rest_encryption_settings() {
+    local enabled_normalized
+    enabled_normalized=$(printf '%s' "${DATA_AT_REST_ENCRYPTION_ENABLED:-false}" | tr '[:upper:]' '[:lower:]')
+
+    if [ "$enabled_normalized" != "1" ] && [ "$enabled_normalized" != "true" ] && [ "$enabled_normalized" != "yes" ] && [ "$enabled_normalized" != "on" ]; then
+        echo -e "${RED}❌ Error: DATA_AT_REST_ENCRYPTION_ENABLED must be true because data-at-rest encryption is mandatory${NC}"
+        exit 1
+    fi
+
+    local has_legacy_private_key=false
+    local has_registry_keys_json=false
+
+    if [ -n "$DATA_AT_REST_ENCRYPTION_PRIVATE_KEY" ] && ! is_placeholder "$DATA_AT_REST_ENCRYPTION_PRIVATE_KEY"; then
+        has_legacy_private_key=true
+    fi
+
+    if [ -n "$DATA_AT_REST_ENCRYPTION_KEYS_JSON" ] && ! is_placeholder "$DATA_AT_REST_ENCRYPTION_KEYS_JSON"; then
+        has_registry_keys_json=true
+    fi
+
+    if [ "$has_legacy_private_key" != "true" ] && [ "$has_registry_keys_json" != "true" ]; then
+        echo -e "${RED}❌ Error: either DATA_AT_REST_ENCRYPTION_PRIVATE_KEY or DATA_AT_REST_ENCRYPTION_KEYS_JSON is required when data-at-rest encryption is enabled${NC}"
+        exit 1
+    fi
+
+    if [ -z "$DATA_AT_REST_ENCRYPTION_PUBLIC_KEY" ] || is_placeholder "$DATA_AT_REST_ENCRYPTION_PUBLIC_KEY"; then
+        echo -e "${RED}❌ Error: DATA_AT_REST_ENCRYPTION_PUBLIC_KEY is required when data-at-rest encryption is enabled${NC}"
+        exit 1
+    fi
+
+    if [ -z "$DATA_AT_REST_ENCRYPTION_KEY_ID" ] || is_placeholder "$DATA_AT_REST_ENCRYPTION_KEY_ID"; then
+        echo -e "${RED}❌ Error: DATA_AT_REST_ENCRYPTION_KEY_ID is required when data-at-rest encryption is enabled${NC}"
+        exit 1
+    fi
+}
+
+validate_user_kv_encryption_settings() {
+    local has_legacy_private_key=false
+    local has_registry_keys_json=false
+    local write_endpoints_enabled_normalized
+
+    if [ -n "$USER_KV_ENCRYPTION_PRIVATE_KEY" ] && ! is_placeholder "$USER_KV_ENCRYPTION_PRIVATE_KEY"; then
+        has_legacy_private_key=true
+    fi
+
+    if [ -n "$USER_KV_ENCRYPTION_KEYS_JSON" ] && ! is_placeholder "$USER_KV_ENCRYPTION_KEYS_JSON"; then
+        has_registry_keys_json=true
+    fi
+
+    if [ "$has_legacy_private_key" != "true" ] && [ "$has_registry_keys_json" != "true" ]; then
+        echo -e "${RED}❌ Error: either USER_KV_ENCRYPTION_PRIVATE_KEY or USER_KV_ENCRYPTION_KEYS_JSON is required${NC}"
+        exit 1
+    fi
+
+    # Defaults to enabled to preserve current behavior unless explicitly set false for read-only deployments.
+    write_endpoints_enabled_normalized=$(printf '%s' "${USER_KV_WRITE_ENDPOINTS_ENABLED:-true}" | tr '[:upper:]' '[:lower:]')
+
+    if [ "$write_endpoints_enabled_normalized" = "1" ] || [ "$write_endpoints_enabled_normalized" = "true" ] || [ "$write_endpoints_enabled_normalized" = "yes" ] || [ "$write_endpoints_enabled_normalized" = "on" ]; then
+        if [ -z "$USER_KV_ENCRYPTION_PUBLIC_KEY" ] || is_placeholder "$USER_KV_ENCRYPTION_PUBLIC_KEY"; then
+            echo -e "${RED}❌ Error: USER_KV_ENCRYPTION_PUBLIC_KEY is required when USER_KV_WRITE_ENDPOINTS_ENABLED is true${NC}"
+            exit 1
+        fi
+
+        if [ -z "$USER_KV_ENCRYPTION_KEY_ID" ] || is_placeholder "$USER_KV_ENCRYPTION_KEY_ID"; then
+            echo -e "${RED}❌ Error: USER_KV_ENCRYPTION_KEY_ID is required when USER_KV_WRITE_ENDPOINTS_ENABLED is true${NC}"
+            exit 1
+        fi
+    fi
+}
+
+# Validate required variables
+required_vars=(
+    # Core Cloudflare Configuration
+    "ACCOUNT_ID"
+
+    # Shared Authentication & Storage
+    "USER_DB_AUTH"
+    "R2_KEY_SECRET"
+    "IMAGES_API_TOKEN"
+
+    # Firebase Auth Configuration
+    "API_KEY"
+    "AUTH_DOMAIN"
+    "PROJECT_ID"
+    "STORAGE_BUCKET"
+    "MESSAGING_SENDER_ID"
+    "APP_ID"
+    "MEASUREMENT_ID"
+    "FIREBASE_SERVICE_ACCOUNT_EMAIL"
+    "FIREBASE_SERVICE_ACCOUNT_PRIVATE_KEY"
+
+    # Pages Configuration
+    "PAGES_PROJECT_NAME"
+    "PAGES_CUSTOM_DOMAIN"
+
+    # Worker Names (required for config replacement)
+    "USER_WORKER_NAME"
+    "DATA_WORKER_NAME"
+    "AUDIT_WORKER_NAME"
+    "IMAGES_WORKER_NAME"
+    "PDF_WORKER_NAME"
+
+    # Worker Domains (required for proxy/env secrets and worker fallbacks)
+    "USER_WORKER_DOMAIN"
+    "DATA_WORKER_DOMAIN"
+    "AUDIT_WORKER_DOMAIN"
+    "IMAGES_WORKER_DOMAIN"
+    "PDF_WORKER_DOMAIN"
+
+    # Storage Configuration (required for config replacement)
+    "DATA_BUCKET_NAME"
+    "AUDIT_BUCKET_NAME"
+    "FILES_BUCKET_NAME"
+    "KV_STORE_ID"
+
+    # Worker-Specific Secrets (required for deployment)
+    "PDF_WORKER_AUTH"
+    "IMAGE_SIGNED_URL_SECRET"
+    "BROWSER_API_TOKEN"
+    "MANIFEST_SIGNING_PRIVATE_KEY"
+    "MANIFEST_SIGNING_KEY_ID"
+    "MANIFEST_SIGNING_PUBLIC_KEY"
+    "EXPORT_ENCRYPTION_PRIVATE_KEY"
+    "EXPORT_ENCRYPTION_KEY_ID"
+    "EXPORT_ENCRYPTION_PUBLIC_KEY"
+)
+
+validate_required_vars() {
+    echo -e "${YELLOW}🔍 Validating required environment variables...${NC}"
+    for var in "${required_vars[@]}"; do
+        if [ -z "${!var}" ] || is_placeholder "${!var}"; then
+            echo -e "${RED}❌ Error: $var is not set in .env file or is a placeholder${NC}"
+            exit 1
+        fi
+    done
+    echo -e "${GREEN}✅ All required variables found${NC}"
+}
+
+assert_file_exists() {
+    local file_path=$1
+
+    if [ ! -f "$file_path" ]; then
+        echo -e "${RED}❌ Error: required file is missing: $file_path${NC}"
+        exit 1
+    fi
+}
+
+assert_contains_literal() {
+    local file_path=$1
+    local literal=$2
+    local description=$3
+
+    if ! grep -Fq -- "$literal" "$file_path"; then
+        echo -e "${RED}❌ Error: ${description}${NC}"
+        echo -e "${YELLOW}   Expected to find '$literal' in $file_path${NC}"
+        exit 1
+    fi
+}
+
+assert_no_match_in_file() {
+    local file_path=$1
+    local pattern=$2
+    local description=$3
+    local matches
+
+    matches=$(grep -En "$pattern" "$file_path" | head -n 3 || true)
+    if [ -n "$matches" ]; then
+        echo -e "${RED}❌ Error: ${description}${NC}"
+        echo -e "${YELLOW}   First matching lines in $file_path:${NC}"
+        echo "$matches"
+        exit 1
+    fi
+}
+
+validate_json_file() {
+    local file_path=$1
+
+    if ! node -e "const fs=require('fs'); JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));" "$file_path" > /dev/null 2>&1; then
+        echo -e "${RED}❌ Error: invalid JSON in $file_path${NC}"
+        exit 1
+    fi
+}
+
+validate_domain_var() {
+    local var_name=$1
+    local value="${!var_name}"
+    local normalized
+
+    value=$(strip_carriage_returns "$value")
+    normalized=$(normalize_domain_value "$value")
+
+    if [ -z "$value" ] || is_placeholder "$value"; then
+        echo -e "${RED}❌ Error: $var_name is missing or placeholder${NC}"
+        exit 1
+    fi
+
+    if [ "$value" != "$normalized" ]; then
+        echo -e "${RED}❌ Error: $var_name must not include protocol, trailing slash, or surrounding whitespace${NC}"
+        echo -e "${YELLOW}   Use '$normalized' instead${NC}"
+        exit 1
+    fi
+
+    if [[ "$value" == */* ]]; then
+        echo -e "${RED}❌ Error: $var_name must be a bare domain (no path segments)${NC}"
+        exit 1
+    fi
+}
+
+validate_env_value_formats() {
+    echo -e "${YELLOW}🔍 Validating environment value formats...${NC}"
+
+    validate_domain_var "PAGES_CUSTOM_DOMAIN"
+    validate_domain_var "USER_WORKER_DOMAIN"
+    validate_domain_var "DATA_WORKER_DOMAIN"
+    validate_domain_var "AUDIT_WORKER_DOMAIN"
+    validate_domain_var "IMAGES_WORKER_DOMAIN"
+    validate_domain_var "PDF_WORKER_DOMAIN"
+
+    if ! [[ "$KV_STORE_ID" =~ ^([0-9a-fA-F]{32}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ ]]; then
+        echo -e "${RED}❌ Error: KV_STORE_ID must be a 32-character hex namespace ID (or UUID format)${NC}"
+        exit 1
+    fi
+
+    if [[ "$ACCOUNT_ID" =~ [[:space:]] ]]; then
+        echo -e "${RED}❌ Error: ACCOUNT_ID must not contain whitespace${NC}"
+        exit 1
+    fi
+
+    echo -e "${GREEN}✅ Environment value formats look valid${NC}"
+}
+
+validate_env_file_entries() {
+    local var_name
+    local escaped_var_name
+    local count
+
+    echo -e "${YELLOW}🔍 Verifying required .env entries...${NC}"
+    for var_name in "${required_vars[@]}"; do
+        escaped_var_name=$(escape_for_sed_pattern "$var_name")
+        count=$(grep -c "^$escaped_var_name=" .env || true)
+
+        if [ "$count" -lt 1 ]; then
+            echo -e "${RED}❌ Error: missing .env entry for $var_name${NC}"
+            exit 1
+        fi
+    done
+    echo -e "${GREEN}✅ Required .env entries found${NC}"
+}
+
+validate_generated_configs() {
+    echo -e "${YELLOW}🔍 Running generated configuration checkpoint validations...${NC}"
+
+    local required_files=(
+        "wrangler.toml"
+        "app/config/config.json"
+        "app/config/firebase.ts"
+        "app/config/admin-service.json"
+        "app/routes/auth/login.tsx"
+        "app/routes/auth/login.module.css"
+        "workers/audit-worker/wrangler.jsonc"
+        "workers/data-worker/wrangler.jsonc"
+        "workers/image-worker/wrangler.jsonc"
+        "workers/pdf-worker/wrangler.jsonc"
+        "workers/user-worker/wrangler.jsonc"
+        "workers/audit-worker/src/audit-worker.ts"
+        "workers/data-worker/src/data-worker.ts"
+        "workers/image-worker/src/image-worker.ts"
+        "workers/pdf-worker/src/pdf-worker.ts"
+        "workers/user-worker/src/user-worker.ts"
+    )
+
+    local file_path
+    for file_path in "${required_files[@]}"; do
+        assert_file_exists "$file_path"
+    done
+
+    validate_json_file "app/config/config.json"
+    validate_json_file "app/config/admin-service.json"
+
+    assert_contains_literal "wrangler.toml" "\"$PAGES_PROJECT_NAME\"" "PAGES_PROJECT_NAME was not applied to wrangler.toml"
+
+    assert_contains_literal "workers/user-worker/wrangler.jsonc" "$USER_WORKER_NAME" "USER_WORKER_NAME was not applied"
+    assert_contains_literal "workers/data-worker/wrangler.jsonc" "$DATA_WORKER_NAME" "DATA_WORKER_NAME was not applied"
+    assert_contains_literal "workers/audit-worker/wrangler.jsonc" "$AUDIT_WORKER_NAME" "AUDIT_WORKER_NAME was not applied"
+    assert_contains_literal "workers/image-worker/wrangler.jsonc" "$IMAGES_WORKER_NAME" "IMAGES_WORKER_NAME was not applied"
+    assert_contains_literal "workers/pdf-worker/wrangler.jsonc" "$PDF_WORKER_NAME" "PDF_WORKER_NAME was not applied"
+
+    assert_contains_literal "workers/user-worker/wrangler.jsonc" "$ACCOUNT_ID" "ACCOUNT_ID missing in user worker config"
+    assert_contains_literal "workers/data-worker/wrangler.jsonc" "$ACCOUNT_ID" "ACCOUNT_ID missing in data worker config"
+    assert_contains_literal "workers/audit-worker/wrangler.jsonc" "$ACCOUNT_ID" "ACCOUNT_ID missing in audit worker config"
+    assert_contains_literal "workers/image-worker/wrangler.jsonc" "$ACCOUNT_ID" "ACCOUNT_ID missing in image worker config"
+    assert_contains_literal "workers/pdf-worker/wrangler.jsonc" "$ACCOUNT_ID" "ACCOUNT_ID missing in pdf worker config"
+
+    assert_contains_literal "workers/data-worker/wrangler.jsonc" "$DATA_BUCKET_NAME" "DATA_BUCKET_NAME missing in data worker config"
+    assert_contains_literal "workers/audit-worker/wrangler.jsonc" "$AUDIT_BUCKET_NAME" "AUDIT_BUCKET_NAME missing in audit worker config"
+    assert_contains_literal "workers/image-worker/wrangler.jsonc" "$FILES_BUCKET_NAME" "FILES_BUCKET_NAME missing in image worker config"
+    assert_contains_literal "workers/user-worker/wrangler.jsonc" "$KV_STORE_ID" "KV_STORE_ID missing in user worker config"
+    assert_contains_literal "workers/user-worker/wrangler.jsonc" "$DATA_BUCKET_NAME" "DATA_BUCKET_NAME missing in user worker config"
+    assert_contains_literal "workers/user-worker/wrangler.jsonc" "$FILES_BUCKET_NAME" "FILES_BUCKET_NAME missing in user worker config"
+
+    assert_contains_literal "app/config/config.json" "https://$PAGES_CUSTOM_DOMAIN" "PAGES_CUSTOM_DOMAIN missing in app/config/config.json"
+    assert_contains_literal "app/config/config.json" "$EXPORT_ENCRYPTION_KEY_ID" "EXPORT_ENCRYPTION_KEY_ID missing in app/config/config.json"
+    assert_contains_literal "app/config/config.json" "\"export_encryption_public_key\":" "export_encryption_public_key missing in app/config/config.json"
+
+    assert_contains_literal "app/config/firebase.ts" "$API_KEY" "API_KEY missing in app/config/firebase.ts"
+    assert_contains_literal "app/config/firebase.ts" "$AUTH_DOMAIN" "AUTH_DOMAIN missing in app/config/firebase.ts"
+    assert_contains_literal "app/config/firebase.ts" "$PROJECT_ID" "PROJECT_ID missing in app/config/firebase.ts"
+    assert_contains_literal "app/config/firebase.ts" "$STORAGE_BUCKET" "STORAGE_BUCKET missing in app/config/firebase.ts"
+    assert_contains_literal "app/config/firebase.ts" "$MESSAGING_SENDER_ID" "MESSAGING_SENDER_ID missing in app/config/firebase.ts"
+    assert_contains_literal "app/config/firebase.ts" "$APP_ID" "APP_ID missing in app/config/firebase.ts"
+    assert_contains_literal "app/config/firebase.ts" "$MEASUREMENT_ID" "MEASUREMENT_ID missing in app/config/firebase.ts"
+
+    assert_contains_literal "workers/audit-worker/src/audit-worker.ts" "https://$PAGES_CUSTOM_DOMAIN" "PAGES_CUSTOM_DOMAIN missing in audit-worker source"
+    assert_contains_literal "workers/data-worker/src/data-worker.ts" "https://$PAGES_CUSTOM_DOMAIN" "PAGES_CUSTOM_DOMAIN missing in data-worker source"
+    assert_contains_literal "workers/image-worker/src/image-worker.ts" "https://$PAGES_CUSTOM_DOMAIN" "PAGES_CUSTOM_DOMAIN missing in image-worker source"
+    assert_contains_literal "workers/pdf-worker/src/pdf-worker.ts" "https://$PAGES_CUSTOM_DOMAIN" "PAGES_CUSTOM_DOMAIN missing in pdf-worker source"
+    assert_contains_literal "workers/user-worker/src/user-worker.ts" "https://$PAGES_CUSTOM_DOMAIN" "PAGES_CUSTOM_DOMAIN missing in user-worker source"
+
+    local placeholder_pattern
+    placeholder_pattern="(\"(ACCOUNT_ID|PAGES_PROJECT_NAME|PAGES_CUSTOM_DOMAIN|USER_WORKER_NAME|DATA_WORKER_NAME|AUDIT_WORKER_NAME|IMAGES_WORKER_NAME|PDF_WORKER_NAME|USER_WORKER_DOMAIN|DATA_WORKER_DOMAIN|AUDIT_WORKER_DOMAIN|IMAGES_WORKER_DOMAIN|PDF_WORKER_DOMAIN|DATA_BUCKET_NAME|AUDIT_BUCKET_NAME|FILES_BUCKET_NAME|KV_STORE_ID|MANIFEST_SIGNING_KEY_ID|MANIFEST_SIGNING_PUBLIC_KEY|EXPORT_ENCRYPTION_KEY_ID|EXPORT_ENCRYPTION_PUBLIC_KEY|YOUR_FIREBASE_API_KEY|YOUR_FIREBASE_AUTH_DOMAIN|YOUR_FIREBASE_PROJECT_ID|YOUR_FIREBASE_STORAGE_BUCKET|YOUR_FIREBASE_MESSAGING_SENDER_ID|YOUR_FIREBASE_APP_ID|YOUR_FIREBASE_MEASUREMENT_ID)\"|'(PAGES_CUSTOM_DOMAIN|DATA_WORKER_DOMAIN|AUDIT_WORKER_DOMAIN|IMAGES_WORKER_DOMAIN)')"
+
+    local files_to_scan=(
+        "wrangler.toml"
+        "workers/audit-worker/wrangler.jsonc"
+        "workers/data-worker/wrangler.jsonc"
+        "workers/image-worker/wrangler.jsonc"
+        "workers/pdf-worker/wrangler.jsonc"
+        "workers/user-worker/wrangler.jsonc"
+        "workers/audit-worker/src/audit-worker.ts"
+        "workers/data-worker/src/data-worker.ts"
+        "workers/image-worker/src/image-worker.ts"
+        "workers/pdf-worker/src/pdf-worker.ts"
+        "workers/user-worker/src/user-worker.ts"
+        "app/config/config.json"
+        "app/config/firebase.ts"
+    )
+
+    for file_path in "${files_to_scan[@]}"; do
+        assert_no_match_in_file "$file_path" "$placeholder_pattern" "Unresolved placeholder token found after config update"
+    done
+
+    echo -e "${GREEN}✅ Generated configuration checkpoint validation passed${NC}"
+}
+
+run_validation_checkpoint() {
+    validate_required_vars
+    validate_env_value_formats
+    validate_env_file_entries
+    validate_data_at_rest_encryption_settings
+    validate_user_kv_encryption_settings
+    validate_generated_configs
+}