From 1b3ce465187775c0c87c6bf413e2998d1a6d0340 Mon Sep 17 00:00:00 2001
From: Matt <matt@letsbe.solutions>
Date: Sun, 7 Dec 2025 11:12:23 +0100
Subject: [PATCH] feat: update agent deployment for secure registration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update docker-compose to use REGISTRATION_TOKEN instead of AGENT_TOKEN
- Require SYSADMIN_REGISTRATION_TOKEN env var in env_setup.sh
- Add instructions for obtaining registration token from orchestrator
- Update credentials.env to document registration token usage

The registration token must now be obtained from the orchestrator API:
POST /api/v1/tenants/{tenant_id}/registration-tokens

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 script/env_setup.sh                       | 21 ++++++++++++++++++++-
 script/stacks/sysadmin/docker-compose.yml | 13 +++++++++++--
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/script/env_setup.sh b/script/env_setup.sh
index 41a7983..ed39cd8 100644
--- a/script/env_setup.sh
+++ b/script/env_setup.sh
@@ -328,6 +328,20 @@ stirlingpdf_postgres_password=$(generate_random_string 40)
 stirlingpdf_api_key=$(generate_random_string 40)
 
 # Sysadmin Agent
+# Registration token must be obtained from orchestrator API:
+# POST /api/v1/tenants/{tenant_id}/registration-tokens
+# The returned token is passed via SYSADMIN_REGISTRATION_TOKEN env var
+sysadmin_registration_token="${SYSADMIN_REGISTRATION_TOKEN:-}"
+if [[ -z "${sysadmin_registration_token}" ]]; then
+    log_error "SYSADMIN_REGISTRATION_TOKEN environment variable is required"
+    log_error "Obtain a registration token from the orchestrator:"
+    log_error "  curl -X POST https://orchestrator.letsbe.biz/api/v1/tenants/{tenant_id}/registration-tokens \\"
+    log_error "       -H 'X-Admin-Api-Key: YOUR_ADMIN_KEY' \\"
+    log_error "       -H 'Content-Type: application/json' \\"
+    log_error "       -d '{\"description\": \"Agent for ${customer}\"}'"
+    die "Missing SYSADMIN_REGISTRATION_TOKEN"
+fi
+# Legacy token (deprecated, kept for backward compatibility)
 sysadmin_agent_token=$(generate_random_string 64)
 
 # ============================================================================
@@ -451,6 +465,7 @@ for file in "${STACKS_DIR}"/*/* "${STACKS_DIR}"/*/.* "${NGINX_DIR}"/* "${SCRIPTS
         sed -i "s/{{ stirlingpdf_postgres_password }}/${stirlingpdf_postgres_password}/g" "${file}"
         sed -i "s/{{ stirlingpdf_api_key }}/${stirlingpdf_api_key}/g" "${file}"
         sed -i "s/{{ sysadmin_agent_token }}/${sysadmin_agent_token}/g" "${file}"
+        sed -i "s/{{ sysadmin_registration_token }}/${sysadmin_registration_token}/g" "${file}"
     fi
 done
 
@@ -496,7 +511,11 @@ MINIO_ROOT_PASSWORD=${minio_root_password}
 KEYCLOAK_ADMIN_PASSWORD=${keycloak_admin_password}
 
 # Sysadmin Agent
-SYSADMIN_AGENT_TOKEN=${sysadmin_agent_token}
+# Note: Registration token is one-time use. After initial registration,
+# agent credentials are persisted to ~/.letsbe-agent/credentials.json
+# and the agent can restart without needing the registration token again.
+SYSADMIN_REGISTRATION_TOKEN=${sysadmin_registration_token}
+# SYSADMIN_AGENT_TOKEN=${sysadmin_agent_token}  # Deprecated
 EOF
 
 # Add Docker Hub section if docker_user was provided
diff --git a/script/stacks/sysadmin/docker-compose.yml b/script/stacks/sysadmin/docker-compose.yml
index 1371d07..12c9888 100644
--- a/script/stacks/sysadmin/docker-compose.yml
+++ b/script/stacks/sysadmin/docker-compose.yml
@@ -10,7 +10,16 @@ services:
     environment:
       # Required: Orchestrator connection
       - ORCHESTRATOR_URL=https://orchestrator.letsbe.biz
-      - AGENT_TOKEN={{ sysadmin_agent_token }}
+
+      # Registration token (new secure flow)
+      # This token is obtained from the orchestrator's registration-tokens API
+      # and is only needed for first-time registration. After registration,
+      # credentials are persisted to ~/.letsbe-agent/credentials.json
+      - REGISTRATION_TOKEN={{ sysadmin_registration_token }}
+
+      # Legacy auth (deprecated - for backward compatibility only)
+      # Uncomment if using older orchestrator version:
+      # - AGENT_TOKEN={{ sysadmin_agent_token }}
 
       # Timing (seconds)
       - HEARTBEAT_INTERVAL=${HEARTBEAT_INTERVAL:-30}
@@ -44,7 +53,7 @@ services:
       - /opt/letsbe/stacks:/opt/letsbe/stacks
       - /opt/letsbe/nginx:/opt/letsbe/nginx
 
-      # Pending results persistence
+      # Credential persistence (survives restarts without re-registration)
       - agent_home:/home/agent/.letsbe-agent
 
     # Run as root for Docker socket access in dev