@striae-org/striae 5.3.1 → 5.4.0

package/app/utils/auth/mfa.ts

@@ -1,7 +1,7 @@
 // MFA Configuration Helper
 // This file contains utilities and documentation for managing MFA in your Firebase project
 
-import { multiFactor, type User } from 'firebase/auth';
+import { multiFactor, PhoneMultiFactorGenerator, TotpMultiFactorGenerator, type User } from 'firebase/auth';
 
 /**
  * Check if a user has MFA enrolled
@@ -35,6 +35,40 @@ export const getMFAFactors = (user: User) => {
   }));
 };
 
+/**
+ * Get enrolled TOTP factors for a user
+ */
+export const getTotpFactors = (user: User) => {
+  return multiFactor(user).enrolledFactors.filter(
+    (factor) => factor.factorId === TotpMultiFactorGenerator.FACTOR_ID
+  );
+};
+
+/**
+ * Check if a user has TOTP MFA enrolled
+ */
+export const hasTotpEnrolled = (user: User): boolean => {
+  return getTotpFactors(user).length > 0;
+};
+
+/**
+ * Get enrolled Phone/SMS factors for a user
+ */
+export const getPhoneMfaFactors = (user: User) => {
+  return multiFactor(user).enrolledFactors.filter(
+    (factor) => factor.factorId === PhoneMultiFactorGenerator.FACTOR_ID
+  );
+};
+
+/**
+ * Return a human-readable label for a factorId
+ */
+export const getMfaMethodLabel = (factorId: string): string => {
+  if (factorId === TotpMultiFactorGenerator.FACTOR_ID) return 'Authenticator App';
+  if (factorId === PhoneMultiFactorGenerator.FACTOR_ID) return 'Phone (SMS)';
+  return 'Unknown Method';
+};
+
 /*
 FIREBASE CONSOLE CONFIGURATION STEPS:
 

package/functions/api/image/[[path]].ts

@@ -67,6 +67,14 @@ function resolveImageWorkerToken(env: Env): string {
   return typeof env.IMAGES_API_TOKEN === 'string' ? env.IMAGES_API_TOKEN.trim() : '';
 }
 
+const BASE64URL_SEGMENT = /^[A-Za-z0-9_-]+$/;
+
+function looksLikeSignedToken(value: string): boolean {
+  const parts = value.split('.');
+  if (parts.length !== 2) return false;
+  return parts.every(part => part.length > 0 && BASE64URL_SEGMENT.test(part));
+}
+
 export const onRequest = async ({ request, env }: ImageProxyContext): Promise<Response> => {
   if (!SUPPORTED_METHODS.has(request.method)) {
     return textResponse('Method not allowed', 405);
@@ -84,9 +92,17 @@ export const onRequest = async ({ request, env }: ImageProxyContext): Promise<Re
 
   const requestUrl = new URL(request.url);
 
-  const identity = await verifyFirebaseIdentityFromRequest(request, env);
-  if (!identity) {
-    return textResponse('Unauthorized', 401);
+  const signedToken = requestUrl.searchParams.get('st');
+  const isSignedTokenRequest =
+    request.method === 'GET' &&
+    signedToken !== null &&
+    looksLikeSignedToken(signedToken);
+
+  if (!isSignedTokenRequest) {
+    const identity = await verifyFirebaseIdentityFromRequest(request, env);
+    if (!identity) {
+      return textResponse('Unauthorized', 401);
+    }
   }
 
   const proxyPathResult = extractProxyPath(requestUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@striae-org/striae",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "private": false,
   "description": "Striae is a specialized, cloud-native platform designed to streamline forensic firearms identification by providing an intuitive environment for digital comparison image annotation, authenticated confirmations, and automated report generation.",
   "license": "Apache-2.0",
@@ -31,27 +31,17 @@
     "access": "public"
   },
   "files": [
-    "app/components/",
-    "app/config-example/",
-    "app/contexts/",
-    "app/hooks/",
-    "app/routes/",
-    "app/services/",
-    "app/styles/",
-    "app/types/",
-    "app/utils/",
-    "app/entry.client.tsx",
-    "app/entry.server.tsx",
-    "app/root.tsx",
-    "app/routes.ts",
-    "app/global.css",
+    "app/",
+    "!app/config",
+    "!app/routes/auth/login.tsx",
+    "!app/routes/auth/login.module.css",
     "react-router.config.ts",
     "load-context.ts",
+    "scripts/",
     "functions/",
     "public/",
     "workers/*/package.json",
     "workers/*/src/**/*.example.ts",
-    "workers/*/src/**/*.example.js",
     "workers/*/src/**/*.ts",
     "workers/pdf-worker/scripts/*.js",
     "!workers/*/src/**/*worker.ts",
@@ -92,6 +82,7 @@
     "typegen": "wrangler types",
     "preview": "npm run build && wrangler pages dev",
     "cf-typegen": "wrangler types",
+    "enable-totp-mfa": "node ./scripts/enable-totp-mfa.mjs",
     "update-versions": "node ./scripts/update-markdown-versions.cjs",
     "update-compatibility-dates": "node ./scripts/update-compatibility-dates.cjs",
     "deploy-config": "bash ./scripts/deploy-config.sh",
@@ -110,9 +101,10 @@
   },
   "dependencies": {
     "@react-router/cloudflare": "^7.13.2",
-    "firebase": "^12.10.0",
-    "isbot": "^5.1.36",
+    "firebase": "^12.11.0",
+    "isbot": "^5.1.37",
     "jszip": "^3.10.1",
+    "qrcode": "^1.5.4",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-router": "^7.13.2"
@@ -120,23 +112,26 @@
   "devDependencies": {
     "@react-router/dev": "^7.13.2",
     "@react-router/fs-routes": "^7.13.2",
+    "@types/qrcode": "^1.5.6",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@typescript-eslint/eslint-plugin": "^8.57.1",
-    "@typescript-eslint/parser": "^8.57.1",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
     "eslint": "^9.39.4",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
+    "firebase-admin": "^13.7.0",
     "modern-normalize": "^3.0.1",
     "typescript": "^5.9.3",
     "vite": "^6.4.1",
     "vite-tsconfig-paths": "^6.1.1",
-    "wrangler": "^4.77.0"
+    "wrangler": "^4.79.0"
   },
   "overrides": {
+    "@tootallnate/once": "3.0.1",
     "tar": "7.5.11",
     "undici": "7.24.1"
   },

package/scripts/deploy-all.sh

@@ -0,0 +1,166 @@
+#!/bin/bash
+
+# ======================================
+# STRIAE COMPLETE DEPLOYMENT SCRIPT
+# ======================================
+# This script deploys the entire Striae application:
+# 1. Configuration setup (copy configs, replace placeholders)
+# 2. Worker dependencies installation
+# 3. Workers (all 5 workers)
+# 4. Worker secrets/environment variables
+# 5. Pages secrets/environment variables
+# 6. Pages (frontend)
+
+set -e
+set -o pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+PURPLE='\033[0;35m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🚀 Striae Complete Deployment Script${NC}"
+echo "======================================"
+echo ""
+
+# Get the script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$PROJECT_ROOT"
+
+trap 'echo -e "\n${RED}❌ deploy-all.sh failed near line ${LINENO}${NC}"' ERR
+
+require_command() {
+    local cmd=$1
+    if ! command -v "$cmd" > /dev/null 2>&1; then
+        echo -e "${RED}❌ Error: required command '$cmd' is not installed or not in PATH${NC}"
+        exit 1
+    fi
+}
+
+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
+}
+
+run_config_checkpoint() {
+    echo -e "${YELLOW}🧪 Running configuration checkpoint validation...${NC}"
+    if ! bash "$SCRIPT_DIR/deploy-config.sh" --validate-only; then
+        echo -e "${RED}❌ Configuration checkpoint validation failed!${NC}"
+        exit 1
+    fi
+    echo -e "${GREEN}✅ Configuration checkpoint validation passed${NC}"
+}
+
+echo -e "${BLUE}🔍 Running deployment preflight checks...${NC}"
+require_command bash
+require_command node
+require_command npm
+require_command wrangler
+
+assert_file_exists "$SCRIPT_DIR/deploy-config.sh"
+assert_file_exists "$SCRIPT_DIR/install-workers.sh"
+assert_file_exists "$SCRIPT_DIR/deploy-worker-secrets.sh"
+assert_file_exists "$SCRIPT_DIR/deploy-pages-secrets.sh"
+assert_file_exists "package.json"
+
+if [ ! -f ".env" ] && [ ! -f ".env.example" ]; then
+    echo -e "${RED}❌ Error: neither .env nor .env.example was found in project root${NC}"
+    exit 1
+fi
+
+echo -e "${GREEN}✅ Preflight checks passed${NC}"
+echo ""
+
+# Step 1: Configuration Setup
+echo -e "${PURPLE}Step 1/6: Configuration Setup${NC}"
+echo "------------------------------"
+echo -e "${YELLOW}⚙️  Setting up configuration files and replacing placeholders...${NC}"
+if ! bash "$SCRIPT_DIR/deploy-config.sh"; then
+    echo -e "${RED}❌ Configuration setup failed!${NC}"
+    echo -e "${YELLOW}Please check your .env file and configuration before proceeding.${NC}"
+    exit 1
+fi
+echo -e "${GREEN}✅ Configuration setup completed successfully${NC}"
+run_config_checkpoint
+echo ""
+
+# Step 2: Install Worker Dependencies
+echo -e "${PURPLE}Step 2/6: Installing Worker Dependencies${NC}"
+echo "----------------------------------------"
+echo -e "${YELLOW}📦 Installing npm dependencies for all workers...${NC}"
+if ! bash "$SCRIPT_DIR/install-workers.sh"; then
+    echo -e "${RED}❌ Worker dependencies installation failed!${NC}"
+    exit 1
+fi
+echo -e "${GREEN}✅ All worker dependencies installed successfully${NC}"
+echo ""
+
+# Step 3: Deploy Workers
+echo -e "${PURPLE}Step 3/6: Deploying Workers${NC}"
+echo "----------------------------"
+echo -e "${YELLOW}🔧 Deploying all 5 Cloudflare Workers...${NC}"
+if ! npm run deploy-workers; then
+    echo -e "${RED}❌ Worker deployment failed!${NC}"
+    exit 1
+fi
+echo -e "${GREEN}✅ All workers deployed successfully${NC}"
+echo ""
+
+# Step 4: Deploy Worker Secrets
+echo -e "${PURPLE}Step 4/6: Deploying Worker Secrets${NC}"
+echo "-----------------------------------"
+echo -e "${YELLOW}🔐 Deploying worker environment variables...${NC}"
+if ! bash "$SCRIPT_DIR/deploy-worker-secrets.sh"; then
+    echo -e "${RED}❌ Worker secrets deployment failed!${NC}"
+    exit 1
+fi
+echo -e "${GREEN}✅ Worker secrets deployed successfully${NC}"
+echo ""
+
+# Step 5: Deploy Pages Secrets
+echo -e "${PURPLE}Step 5/6: Deploying Pages Secrets${NC}"
+echo "----------------------------------"
+echo -e "${YELLOW}🔐 Deploying Pages environment variables to production only...${NC}"
+if ! bash "$SCRIPT_DIR/deploy-pages-secrets.sh" --production-only; then
+    echo -e "${RED}❌ Pages secrets deployment failed!${NC}"
+    exit 1
+fi
+echo -e "${GREEN}✅ Pages secrets deployed successfully${NC}"
+echo ""
+
+# Step 6: Deploy Pages
+echo -e "${PURPLE}Step 6/6: Deploying Pages${NC}"
+echo "--------------------------"
+echo -e "${YELLOW}🌐 Building and deploying Pages...${NC}"
+if ! npm run deploy-pages; then
+    echo -e "${RED}❌ Pages deployment failed!${NC}"
+    exit 1
+fi
+echo -e "${GREEN}✅ Pages deployed successfully${NC}"
+echo ""
+
+# Success summary
+echo "=========================================="
+echo -e "${GREEN}🎉 COMPLETE DEPLOYMENT SUCCESSFUL! 🎉${NC}"
+echo "=========================================="
+echo ""
+echo -e "${BLUE}Deployed Components:${NC}"
+echo "  ✅ Worker dependencies (npm install)"
+echo "  ✅ 5 Cloudflare Workers"
+echo "  ✅ Worker environment variables"
+echo "  ✅ Pages environment variables"
+echo "  ✅ Cloudflare Pages frontend"
+echo ""
+echo -e "${BLUE}Next Steps:${NC}"
+echo "  1. Test your application endpoints"
+echo "  2. Verify all services are working"
+echo "  3. Verify worker and Pages secrets are set as expected"
+echo ""
+echo -e "${GREEN}✨ Your Striae application is now fully deployed!${NC}"

package/scripts/deploy-config/modules/env-utils.sh

@@ -0,0 +1,322 @@
+#!/bin/bash
+
+escape_for_sed_pattern() {
+    printf '%s' "$1" | sed -e 's/[][\\.^$*+?{}|()]/\\&/g'
+}
+
+dedupe_env_var_entries() {
+    local var_name=$1
+    local expected_count=1
+    local escaped_var_name
+
+    escaped_var_name=$(escape_for_sed_pattern "$var_name")
+
+    if [ -f ".env.example" ]; then
+        expected_count=$(grep -c "^$escaped_var_name=" .env.example || true)
+
+        if [ "$expected_count" -lt 1 ]; then
+            expected_count=1
+        fi
+    fi
+
+    awk -v key="$var_name" -v keep="$expected_count" '
+        BEGIN { seen = 0 }
+        {
+            if (index($0, key "=") == 1) {
+                seen++
+
+                if (seen > keep) {
+                    next
+                }
+            }
+            print
+        }
+    ' .env > .env.tmp && mv .env.tmp .env
+}
+
+normalize_domain_value() {
+    local domain="$1"
+
+    domain=$(printf '%s' "$domain" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+    domain="${domain#http://}"
+    domain="${domain#https://}"
+    domain="${domain%/}"
+
+    printf '%s' "$domain"
+}
+
+normalize_worker_label_value() {
+    local label="$1"
+
+    label=$(normalize_domain_value "$label")
+    label="${label#.}"
+    label="${label%.}"
+    label=$(printf '%s' "$label" | tr '[:upper:]' '[:lower:]')
+
+    printf '%s' "$label"
+}
+
+normalize_worker_subdomain_value() {
+    local subdomain="$1"
+
+    subdomain=$(normalize_domain_value "$subdomain")
+    subdomain="${subdomain#.}"
+    subdomain="${subdomain%.}"
+    subdomain=$(printf '%s' "$subdomain" | tr '[:upper:]' '[:lower:]')
+
+    printf '%s' "$subdomain"
+}
+
+is_valid_worker_label() {
+    local label="$1"
+
+    [[ "$label" =~ ^[a-z0-9-]+$ ]]
+}
+
+is_valid_worker_subdomain() {
+    local subdomain="$1"
+
+    [[ "$subdomain" =~ ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ ]]
+}
+
+strip_carriage_returns() {
+    printf '%s' "$1" | tr -d '\r'
+}
+
+read_env_var_from_file() {
+    local env_file=$1
+    local var_name=$2
+
+    if [ ! -f "$env_file" ]; then
+        return 0
+    fi
+
+    awk -v key="$var_name" '
+        index($0, key "=") == 1 {
+            value = substr($0, length(key) + 2)
+        }
+        END {
+            if (value != "") {
+                gsub(/\r/, "", value)
+                gsub(/^"/, "", value)
+                gsub(/"$/, "", value)
+                print value
+            }
+        }
+    ' "$env_file"
+}
+
+resolve_existing_domain_value() {
+    local var_name=$1
+    local current_value=$2
+    local preserved_value=""
+
+    current_value=$(normalize_domain_value "$current_value")
+
+    if [ "$current_value" = "$var_name" ]; then
+        current_value=""
+    fi
+
+    if [ -n "$current_value" ] && ! is_placeholder "$current_value"; then
+        printf '%s' "$current_value"
+        return 0
+    fi
+
+    if [ -n "$preserved_domain_env_file" ] && [ -f "$preserved_domain_env_file" ]; then
+        preserved_value=$(read_env_var_from_file "$preserved_domain_env_file" "$var_name")
+        preserved_value=$(normalize_domain_value "$preserved_value")
+
+        if [ "$preserved_value" = "$var_name" ]; then
+            preserved_value=""
+        fi
+
+        if [ -n "$preserved_value" ] && ! is_placeholder "$preserved_value"; then
+            printf '%s' "$preserved_value"
+            return 0
+        fi
+    fi
+
+    printf '%s' "$current_value"
+}
+
+restore_env_var_from_backup_if_missing() {
+    local var_name=$1
+    local current_value="${!var_name}"
+    local preserved_value=""
+
+    if [ "$update_env" != "true" ]; then
+        return 0
+    fi
+
+    if [ -z "$preserved_domain_env_file" ] || [ ! -f "$preserved_domain_env_file" ]; then
+        return 0
+    fi
+
+    current_value=$(strip_carriage_returns "$current_value")
+
+    if [ -n "$current_value" ] && ! is_placeholder "$current_value"; then
+        return 0
+    fi
+
+    preserved_value=$(read_env_var_from_file "$preserved_domain_env_file" "$var_name")
+    preserved_value=$(strip_carriage_returns "$preserved_value")
+
+    if [ -z "$preserved_value" ] || is_placeholder "$preserved_value"; then
+        return 0
+    fi
+
+    printf -v "$var_name" '%s' "$preserved_value"
+    export "$var_name"
+    write_env_var "$var_name" "$preserved_value"
+}
+
+confirm_key_pair_regeneration() {
+    local key_pair_label=$1
+    local impact_warning=$2
+    local regenerate_choice=""
+
+    if [ "$force_rotate_keys" = "true" ]; then
+        echo -e "${YELLOW}⚠️  Auto-confirmed regeneration for $key_pair_label key pair (--force-rotate-keys).${NC}"
+        return 0
+    fi
+
+    echo -e "${GREEN}Current $key_pair_label key pair: [HIDDEN]${NC}"
+
+    if [ -n "$impact_warning" ]; then
+        echo -e "${YELLOW}⚠️  $impact_warning${NC}"
+    fi
+
+    read -p "Regenerate $key_pair_label key pair? (press Enter to keep current, or type 'y' to regenerate): " regenerate_choice
+    regenerate_choice=$(strip_carriage_returns "$regenerate_choice")
+
+    if [ "$regenerate_choice" = "y" ] || [ "$regenerate_choice" = "Y" ]; then
+        return 0
+    fi
+
+    return 1
+}
+
+generate_worker_subdomain_label() {
+    node -e "const { randomInt } = require('crypto'); const alphabet = 'abcdefghijklmnopqrstuvwxyz0123456789'; let value = ''; for (let index = 0; index < 10; index += 1) { value += alphabet[randomInt(alphabet.length)]; } process.stdout.write(value);" 2>/dev/null
+}
+
+compose_worker_domain() {
+    local worker_name=$1
+    local worker_subdomain=$2
+
+    worker_name=$(normalize_worker_label_value "$worker_name")
+    worker_subdomain=$(normalize_worker_subdomain_value "$worker_subdomain")
+
+    if [ -z "$worker_name" ] || [ -z "$worker_subdomain" ]; then
+        return 1
+    fi
+
+    if ! is_valid_worker_label "$worker_name" || ! is_valid_worker_subdomain "$worker_subdomain"; then
+        return 1
+    fi
+
+    printf '%s.%s' "$worker_name" "$worker_subdomain"
+}
+
+infer_worker_subdomain_from_domain() {
+    local worker_name=$1
+    local worker_domain=$2
+    local worker_subdomain=""
+
+    worker_name=$(normalize_worker_label_value "$worker_name")
+    worker_domain=$(normalize_domain_value "$worker_domain")
+    worker_domain=$(printf '%s' "$worker_domain" | tr '[:upper:]' '[:lower:]')
+
+    if [ -z "$worker_name" ] || [ -z "$worker_domain" ] || is_placeholder "$worker_name" || is_placeholder "$worker_domain"; then
+        printf '%s' ""
+        return 0
+    fi
+
+    case "$worker_domain" in
+        "$worker_name".*)
+            worker_subdomain="${worker_domain#${worker_name}.}"
+            worker_subdomain=$(normalize_worker_subdomain_value "$worker_subdomain")
+
+            if is_valid_worker_subdomain "$worker_subdomain"; then
+                printf '%s' "$worker_subdomain"
+                return 0
+            fi
+            ;;
+    esac
+
+    printf '%s' ""
+}
+
+write_env_var() {
+    local var_name=$1
+    local var_value=$2
+    local env_file_value="$var_value"
+
+    var_value=$(strip_carriage_returns "$var_value")
+    env_file_value="$var_value"
+
+    if [ "$var_name" = "FIREBASE_SERVICE_ACCOUNT_PRIVATE_KEY" ] || [ "$var_name" = "MANIFEST_SIGNING_PRIVATE_KEY" ] || [ "$var_name" = "MANIFEST_SIGNING_PUBLIC_KEY" ] || [ "$var_name" = "EXPORT_ENCRYPTION_PRIVATE_KEY" ] || [ "$var_name" = "EXPORT_ENCRYPTION_PUBLIC_KEY" ] || [ "$var_name" = "DATA_AT_REST_ENCRYPTION_PRIVATE_KEY" ] || [ "$var_name" = "DATA_AT_REST_ENCRYPTION_PUBLIC_KEY" ] || [ "$var_name" = "USER_KV_ENCRYPTION_PRIVATE_KEY" ] || [ "$var_name" = "USER_KV_ENCRYPTION_PUBLIC_KEY" ] || [ "$var_name" = "EXPORT_ENCRYPTION_KEYS_JSON" ] || [ "$var_name" = "DATA_AT_REST_ENCRYPTION_KEYS_JSON" ] || [ "$var_name" = "USER_KV_ENCRYPTION_KEYS_JSON" ]; then
+        # Store as a quoted string so sourced .env preserves escaped newline markers (\n)
+        env_file_value=${env_file_value//\"/\\\"}
+        env_file_value="\"$env_file_value\""
+    fi
+
+    local escaped_var_name
+    local replacement_line
+    escaped_var_name=$(escape_for_sed_pattern "$var_name")
+    replacement_line=$(escape_for_sed_replacement "$var_name=$env_file_value")
+
+    if grep -q "^$escaped_var_name=" .env; then
+        # Replace all occurrences so intentional duplicates in .env.example stay in sync.
+        sed -i "s|^$escaped_var_name=.*|$replacement_line|g" .env
+        dedupe_env_var_entries "$var_name"
+    else
+        echo "$var_name=$env_file_value" >> .env
+    fi
+}
+
+update_private_key_registry() {
+    local registry_var_name=$1
+    local active_key_var_name=$2
+    local current_key_id=$3
+    local private_key_value=$4
+    local registry_label=$5
+    local existing_registry_json=""
+    local updated_registry_json=""
+    local registry_entry_count=""
+
+    if [ -z "$registry_var_name" ] || [ -z "$active_key_var_name" ] || [ -z "$current_key_id" ] || [ -z "$private_key_value" ]; then
+        echo -e "${YELLOW}⚠️  Skipping $registry_label key registry update due to missing inputs${NC}"
+        return 0
+    fi
+
+    existing_registry_json="${!registry_var_name}"
+    existing_registry_json=$(strip_carriage_returns "$existing_registry_json")
+
+    if [ -z "$existing_registry_json" ] || is_placeholder "$existing_registry_json"; then
+        existing_registry_json="{}"
+    fi
+
+    updated_registry_json=$(node -e "const raw = process.argv[1] || '{}'; const keyId = process.argv[2] || ''; const privateKey = process.argv[3] || ''; if (!keyId || !privateKey) process.exit(1); const normalized = { activeKeyId: null, keys: {} }; try { const parsed = JSON.parse(raw); if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) { if (parsed.keys && typeof parsed.keys === 'object' && !Array.isArray(parsed.keys)) { normalized.keys = Object.fromEntries(Object.entries(parsed.keys).filter(([id, pem]) => typeof id === 'string' && id.trim().length > 0 && typeof pem === 'string' && pem.trim().length > 0)); if (typeof parsed.activeKeyId === 'string' && parsed.activeKeyId.trim().length > 0) normalized.activeKeyId = parsed.activeKeyId.trim(); } else { normalized.keys = Object.fromEntries(Object.entries(parsed).filter(([id, pem]) => id !== 'activeKeyId' && id !== 'keys' && typeof id === 'string' && id.trim().length > 0 && typeof pem === 'string' && pem.trim().length > 0)); if (typeof parsed.activeKeyId === 'string' && parsed.activeKeyId.trim().length > 0) normalized.activeKeyId = parsed.activeKeyId.trim(); } } } catch (_) {} normalized.keys[keyId] = privateKey; normalized.activeKeyId = keyId; process.stdout.write(JSON.stringify(normalized));" "$existing_registry_json" "$current_key_id" "$private_key_value" 2>/dev/null || true)
+
+    if [ -z "$updated_registry_json" ]; then
+        echo -e "${RED}❌ Error: Failed to update $registry_label key registry JSON${NC}"
+        exit 1
+    fi
+
+    printf -v "$registry_var_name" '%s' "$updated_registry_json"
+    export "$registry_var_name"
+    write_env_var "$registry_var_name" "$updated_registry_json"
+
+    printf -v "$active_key_var_name" '%s' "$current_key_id"
+    export "$active_key_var_name"
+    write_env_var "$active_key_var_name" "$current_key_id"
+
+    registry_entry_count=$(node -e "const raw = process.argv[1] || '{}'; try { const parsed = JSON.parse(raw); if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { process.stdout.write('0'); process.exit(0); } const keys = parsed.keys && typeof parsed.keys === 'object' && !Array.isArray(parsed.keys) ? parsed.keys : parsed; const count = Object.entries(keys).filter(([id, pem]) => id !== 'activeKeyId' && id !== 'keys' && typeof id === 'string' && id.trim().length > 0 && typeof pem === 'string' && pem.trim().length > 0).length; process.stdout.write(String(count)); } catch (_) { process.stdout.write('0'); }" "$updated_registry_json")
+    echo -e "${GREEN}✅ Updated $registry_label key registry ($registry_entry_count key IDs tracked)${NC}"
+    echo -e "${GREEN}✅ $active_key_var_name: $current_key_id${NC}"
+}
+
+escape_for_sed_replacement() {
+    printf '%s' "$1" | sed -e 's/[&|\\]/\\&/g'
+}