direxio-deployer 0.1.0

package/scripts/phases/s0_prereq_aws.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# S0 PREREQ_AWS - validate that AWS credentials are usable.
+#
+# User-side AWS account/IAM/key setup is documented in references/user-journey.md.
+# This phase only validates credentials and reports actionable blockers.
+
+run_phase() {
+  aws_env_prep
+
+  # STS is the source of truth and supports env keys, AWS_PROFILE, instance roles, SSO, etc.
+  phase_set S0_PREREQ_AWS in_progress "validating AWS credentials"
+  local acct arn
+  arn=$(aws_identity_arn)
+  if [ -n "$arn" ] && [ "$arn" != "None" ]; then
+    local root_identity=false
+    aws_arn_is_root "$arn" && root_identity=true
+    acct=$(aws_identity_account)
+    state_set region "${AWS_DEFAULT_REGION:-$(state_get region)}"
+    phase_set S0_PREREQ_AWS done "sts ok account=$acct profile=${AWS_PROFILE:-<env/ak>} root=$root_identity arn=$(aws_redact_arn "$arn") region=${AWS_DEFAULT_REGION:-$(state_get region)}"
+    ok "AWS credentials are valid (account=$acct${AWS_PROFILE:+, profile=$AWS_PROFILE}, root=$root_identity, arn=$(aws_redact_arn "$arn"))."
+    return 0
+  fi
+
+  # Distinguish missing credentials from invalid/not-yet-active credentials.
+  if [ -z "${AWS_ACCESS_KEY_ID:-}" ] && [ -z "${AWS_PROFILE:-}" ]; then
+    phase_set S0_PREREQ_AWS waiting_user "no usable AWS credentials (no env keys or AWS_PROFILE)"
+    warn "No usable AWS credentials found. Choose one:"
+    warn "  1. Configure a deployment access key, then export AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=..."
+    warn "  2. Or use an existing profile: export AWS_PROFILE=<your-profile>"
+    return 2
+  fi
+
+  phase_set S0_PREREQ_AWS waiting_user "sts failed (invalid credentials, not active yet, or proxy/TLS issue)"
+  warn "AWS credential validation failed (profile=${AWS_PROFILE:-<env/ak>}). Possible causes:"
+  warn "  1. AK/SK or profile is incorrect."
+  warn "  2. Newly created credentials are not active yet; wait a few minutes."
+  warn "  3. Local proxy/network is breaking TLS; AWS proxy bypass is already attempted."
+  return 2
+}

package/scripts/phases/s1_preflight.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# S1 PREFLIGHT - default VPC, EC2 vCPU quota, and AMI checks.
+#
+# New AWS accounts often start with low or zero EC2 quota. Report the blocker
+# and keep polling instead of losing deployment state.
+
+run_phase() {
+  aws_env_prep
+  phase_set S1_PREFLIGHT in_progress "running preflight checks"
+
+  # 1) Default VPC.
+  local vpc
+  vpc=$(aws ec2 describe-vpcs --filters Name=isDefault,Values=true \
+        --query 'Vpcs[0].VpcId' --output text 2>/dev/null || echo "None")
+  if [ "$vpc" = "None" ] || [ -z "$vpc" ]; then
+    phase_set S1_PREFLIGHT failed "no default VPC in this region"
+    fail "This region has no default VPC. In the AWS console, go to VPC -> Create default VPC, or choose another region."
+  fi
+  res_set vpc_id "$vpc"
+  log "Default VPC = $vpc"
+
+  # 2) vCPU quota. t3.small requires 2 vCPU. Unknown quota is warned but not blocked.
+  local quota
+  quota=$(aws service-quotas get-service-quota --service-code ec2 --quota-code "$EC2_STD_QUOTA_CODE" \
+          --query 'Quota.Value' --output text 2>/dev/null || echo "unknown")
+  quota=${quota:-unknown}
+  log "On-Demand Standard instance vCPU quota = $quota (need 2)"
+  if _is_unknown_quota "$quota"; then
+    warn "Could not read quota; continuing. If run-instances returns VcpuLimitExceeded, quota is insufficient."
+  elif ! _num_ge "$quota" 2; then
+    phase_set S1_PREFLIGHT waiting_user "vCPU quota=$quota (<2), waiting for quota increase"
+    warn "EC2 vCPU quota is $quota (<2), which is common on new AWS accounts."
+    warn "Open Service Quotas -> Amazon EC2 ->"
+    warn "  'Running On-Demand Standard (A,C,D,H,I,M,R,T,Z) instances' and request quota >= 2."
+    warn "After submitting the request, you can leave this running; it checks every ${QUOTA_POLL_INTERVAL:-300}s."
+    poll_until "vCPU quota >= 2" "${QUOTA_POLL_INTERVAL:-300}" 0 _quota_ge_2 \
+      || { phase_set S1_PREFLIGHT failed "quota polling interrupted"; return 1; }
+  fi
+
+  # 3) AMI (amd64/x86).
+  local ami
+  ami=$(aws_lookup_ubuntu_ami)
+  if [ "$ami" = "None" ] || [ -z "$ami" ]; then
+    phase_set S1_PREFLIGHT failed "failed to resolve Ubuntu AMI"
+    fail "Could not resolve Ubuntu 22.04 amd64 AMI (SSM parameter unavailable)."
+  fi
+  res_set ami_id "$ami"
+  log "AMI = $ami (Ubuntu 22.04 amd64/x86, user=ubuntu)"
+
+  phase_set S1_PREFLIGHT done "vpc=$vpc quota=$quota ami=$ami"
+  return 0
+}
+
+# Values used when quota cannot be read. These warn but do not block.
+_is_unknown_quota() {
+  case "$1" in ""|unknown|None|null) return 0;; *) return 1;; esac
+}
+
+# Numeric comparison $1 >= $2. Use -v to avoid awk syntax errors on empty/non-numeric input.
+_num_ge() {
+  awk -v a="$1" -v b="$2" 'BEGIN{ if (a+0 >= b+0) exit 0; else exit 1 }'
+}
+
+# Quota >= 2 check for poll_until. Empty/None counts as not ready.
+_quota_ge_2() {
+  local q
+  q=$(aws service-quotas get-service-quota --service-code ec2 --quota-code "$EC2_STD_QUOTA_CODE" \
+      --query 'Quota.Value' --output text 2>/dev/null || echo "0")
+  q=${q:-0}
+  _is_unknown_quota "$q" && return 1
+  _num_ge "$q" 2
+}

package/scripts/phases/s2_domain.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# S2 DOMAIN_DECISION — validate the production Matrix server_name.
+#
+# P2P-IM production deployments require a real, long-lived domain. Temporary
+# sslip.io/public-IP domains are intentionally not part of this interface.
+#
+# Supported modes:
+#   DOMAIN_MODE=user    user owns DNS; S3 waits until A record points at the EIP
+#   DOMAIN_MODE=route53 Route53 hosted zone; ops manages the A record
+#
+# If DOMAIN_MODE is omitted but DOMAIN is present, user mode is assumed.
+# P2P_ASSUME_DEFAULTS never chooses a domain.
+
+S2_PHASE_DIR=$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." && pwd)
+source "$S2_PHASE_DIR/lib/domain.sh"
+
+run_phase() {
+  phase_set S2_DOMAIN in_progress "validating production domain"
+
+  local mode=${DOMAIN_MODE:-}
+  local domain=${DOMAIN:-}
+
+  if [ -z "$mode" ]; then
+    if [ -n "$domain" ]; then
+      mode=user
+    elif [ -t 0 ]; then
+      warn "P2P-IM requires a production domain as the Matrix server_name."
+      warn "Changing the domain is effectively a new homeserver identity; temporary sslip.io defaults are not supported."
+      printf "Enter the final domain (for example __DOMAIN__): " >&2
+      read -r domain
+      [ -n "$domain" ] || {
+        phase_set S2_DOMAIN waiting_user "waiting for production domain"
+        warn "DOMAIN was not provided. Prepare a production domain and DNS control first."
+        return 2
+      }
+      mode=user
+    else
+      phase_set S2_DOMAIN waiting_user "waiting for production domain"
+      warn "Deployment blocked: DOMAIN is missing. P2P-IM no longer supports temporary sslip.io defaults."
+      warn "Prepare a production domain such as __DOMAIN__. Matrix server_name binds to that domain; changing it later is effectively a new homeserver identity."
+      warn "Example:"
+      warn "  DOMAIN=__DOMAIN__ DOMAIN_MODE=user CONFIRM_DOMAIN_BINDING=1 bash scripts/orchestrate.sh"
+      return 2
+    fi
+  fi
+
+  if [ -z "$domain" ]; then
+    phase_set S2_DOMAIN waiting_user "$mode mode requires DOMAIN"
+    warn "Deployment blocked: DOMAIN_MODE=$mode requires explicit DOMAIN."
+    warn "Example: DOMAIN=__DOMAIN__ DOMAIN_MODE=$mode CONFIRM_DOMAIN_BINDING=1 bash scripts/orchestrate.sh"
+    return 2
+  fi
+  domain=$(domain_normalize "$domain")
+  if ! domain_is_formal_name "$domain"; then
+    phase_set S2_DOMAIN waiting_user "DOMAIN is not a valid production domain"
+    warn "Deployment blocked: DOMAIN=$domain is not a valid production domain."
+    warn "Use a long-lived domain you own and can manage in DNS, such as __DOMAIN__. IPs, localhost, wildcards, and temporary resolver domains are not accepted."
+    return 2
+  fi
+
+  if [ "${CONFIRM_DOMAIN_BINDING:-0}" != "1" ]; then
+    phase_set S2_DOMAIN waiting_user "domain binding irreversibility not confirmed"
+    warn "Deployment blocked: Matrix server_name domain binding must be confirmed."
+    warn "After $domain becomes server_name, changing the domain is effectively a new homeserver identity."
+    warn "Rerun after confirmation:"
+    warn "  DOMAIN=$domain DOMAIN_MODE=$mode CONFIRM_DOMAIN_BINDING=1 bash scripts/orchestrate.sh"
+    return 2
+  fi
+
+  case "$mode" in
+    user)
+      state_set domain_mode user
+      state_set domain "$domain"
+      state_set_raw domain_confirmed_irreversible 'true'
+      warn "Domain mode = user ($domain). S3 will wait for the DNS A record to point at the new EIP."
+      warn "If DNS is hosted on Cloudflare, set the record to DNS only; do not enable proxying."
+      ;;
+    route53)
+      state_set domain_mode route53
+      state_set domain "$domain"
+      state_set_raw domain_confirmed_irreversible 'true'
+      log "Domain mode = route53 ($domain). The agent will create the A record automatically; IAM needs Route53 permissions."
+      ;;
+    buy)
+      phase_set S2_DOMAIN waiting_user "automatic domain purchase disabled"
+      warn "buy mode is disabled: ops will not purchase domains automatically."
+      warn "Domain purchase involves billing, identity/compliance steps, and irreversible ownership decisions."
+      warn "Prepare the domain manually, then use DOMAIN=$domain with DOMAIN_MODE=user or DOMAIN_MODE=route53."
+      return 2
+      ;;
+    *)
+      phase_set S2_DOMAIN failed "unknown DOMAIN_MODE=$mode"
+      fail "Unknown DOMAIN_MODE=$mode (expected user|route53; ec2 temporary-domain mode was removed, buy mode is disabled)." ;;
+  esac
+
+  if [ "${DOMAIN_VERIFIED:-0}" != "1" ] && ! domain_has_dns_record "$domain"; then
+    warn "No A/AAAA/CNAME record was found for $domain."
+    warn "If this is a new domain, confirm DNS hosting is active. S3 will still wait for the A record to point at the new EIP."
+  fi
+
+  phase_set S2_DOMAIN done "mode=$mode domain=$domain"
+  return 0
+}

package/scripts/phases/s3_provision.sh

@@ -0,0 +1,421 @@
+#!/usr/bin/env bash
+# S3 PROVISION_EC2 - key pair, security group, cloud-init, EC2, EIP, DNS.
+#
+# Default instance type is x86/amd64 t3.small (2 vCPU / 2GB). Every resource is
+# persisted immediately so deployment can resume and destroy.sh can clean up.
+
+S3_PHASE_DIR=$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." && pwd)
+source "$S3_PHASE_DIR/lib/domain.sh"
+
+run_phase() {
+  aws_env_prep
+  phase_set S3_PROVISION in_progress "provisioning EC2"
+
+  local name region instance_type ami sg vpc
+  name=$(state_get run_id)
+  region=$(state_get region)
+  instance_type=$(state_get instance_type)
+  if [ -z "$instance_type" ]; then
+    instance_type=${INSTANCE_TYPE:-}
+    if [ -z "$instance_type" ]; then
+      if [ "${P2P_ASSUME_DEFAULTS:-0}" = "1" ]; then
+        instance_type=t3.small
+      elif [ -t 0 ]; then
+        warn "Default EC2 instance type is t3.small (2 vCPU / 2GB). Do you need a larger instance?"
+        printf "Use a larger instance? [y/N] " >&2
+        local ans chosen
+        read -r ans
+        if is_yes "$ans"; then
+          printf "Enter EC2 instance type [t3.medium]: " >&2
+          read -r chosen
+          instance_type=${chosen:-t3.medium}
+        else
+          instance_type=t3.small
+        fi
+      else
+        phase_set S3_PROVISION waiting_user "waiting for EC2 instance type confirmation"
+        warn "EC2 instance type must be confirmed. Default t3.small = 2 vCPU / 2GB."
+        warn "  Use default: INSTANCE_TYPE=t3.small bash scripts/orchestrate.sh"
+        warn "  Use larger:  INSTANCE_TYPE=t3.medium bash scripts/orchestrate.sh"
+        warn "  Larger instances require matching vCPU quota. If run-instances returns VcpuLimitExceeded, return to S1 and request quota."
+        return 2
+      fi
+    fi
+    state_set instance_type "$instance_type"
+  fi
+  if declare -F ensure_cost_estimate >/dev/null 2>&1; then
+    ensure_cost_estimate
+  fi
+  ami=$(res_get ami_id)
+  vpc=$(res_get vpc_id)
+  local message_server_image
+  message_server_image=${MESSAGE_SERVER_IMAGE:-direxio/message-server:latest}
+  local scripts_dir=${P2P_INSTALL_SCRIPTS_DIR:-${HERE:-$S3_PHASE_DIR}}
+
+  # 1) Key pair (idempotent).
+  local keyfile="$P2P_WORKDIR/${name}.pem"
+  if [ -z "$(res_get key_name)" ]; then
+    log "Creating key pair $name ..."
+    aws ec2 create-key-pair --key-name "$name" --query KeyMaterial --output text > "$keyfile"
+    chmod 600 "$keyfile"
+    res_set key_name "$name"; res_set key_file "$keyfile"
+  else
+    log "Key pair already exists; skipping."; keyfile=$(res_get key_file)
+  fi
+
+  # 2) Security group (idempotent): 22/80/443 + TURN relay ports.
+  if [ -z "$(res_get sg_id)" ]; then
+    log "Creating security group (22/80/443 + TURN 3478/49160-49200)..."
+    warn "Security group opens 22/80/443, TURN 3478 tcp/udp, and 49160-49200/udp to 0.0.0.0/0."
+    warn "Keep the SSH private key, AWS credentials, and password secure."
+    sg=$(aws ec2 create-security-group --group-name "$name" \
+         --description "p2p-matrix $name" --vpc-id "$vpc" --query GroupId --output text)
+    res_set sg_id "$sg"
+    local p
+    for p in 22 80 443; do
+      aws ec2 authorize-security-group-ingress --group-id "$sg" \
+        --protocol tcp --port "$p" --cidr 0.0.0.0/0 >/dev/null
+    done
+    # TURN main port 3478 (udp+tcp); first version does not expose turns:5349.
+    aws ec2 authorize-security-group-ingress --group-id "$sg" --protocol tcp --port 3478 --cidr 0.0.0.0/0 >/dev/null
+    aws ec2 authorize-security-group-ingress --group-id "$sg" --protocol udp --port 3478 --cidr 0.0.0.0/0 >/dev/null
+    # Narrow TURN UDP relay range to 49160-49200.
+    aws ec2 authorize-security-group-ingress --group-id "$sg" --protocol udp --port 49160-49200 --cidr 0.0.0.0/0 >/dev/null
+  else
+    log "Security group already exists; skipping."; sg=$(res_get sg_id)
+  fi
+
+  # 3) Render cloud-init with compose/Caddyfile/init-tokens embedded.
+  local domain_mode domain
+  domain_mode=$(state_get domain_mode)
+  domain=$(state_get domain)
+  domain=$(domain_normalize "$domain")
+  if [ -z "$domain" ]; then
+    phase_set S3_PROVISION waiting_user "production domain missing"
+    warn "S3 requires a production DOMAIN. Complete S2_DOMAIN first."
+    return 2
+  fi
+  local userdata="$P2P_WORKDIR/user-data.yaml"
+  log "Rendering cloud-init (domain_mode=$domain_mode)..."
+  bash "$scripts_dir/render/render-userdata.sh" \
+    --domain "$domain" \
+    --acme "${ACME_EMAIL:-}" \
+    --message-server-image "$message_server_image" \
+    > "$userdata"
+  local userdata_aws="$userdata"
+  if command -v cygpath >/dev/null 2>&1; then
+    userdata_aws=$(cygpath -w "$userdata")
+  fi
+
+  # 4) Launch EC2 (idempotent: reuse running/pending instance).
+  local iid
+  iid=$(res_get instance_id)
+  if [ -n "$iid" ] && aws ec2 describe-instances --instance-ids "$iid" \
+        --query 'Reservations[0].Instances[0].State.Name' --output text 2>/dev/null \
+        | grep -qE 'running|pending'; then
+    log "Instance $iid already exists; skipping creation."
+  else
+    log "Launching EC2 instance (x86 $instance_type, $ami)..."
+    iid=$(aws ec2 run-instances --image-id "$ami" --instance-type "$instance_type" \
+      --key-name "$name" --security-group-ids "$sg" \
+      --user-data "file://$userdata_aws" \
+      --tag-specifications "ResourceType=instance,Tags=[{Key=Name,Value=$name}]" \
+      --query 'Instances[0].InstanceId' --output text) || {
+        phase_set S3_PROVISION failed "run-instances failed (possibly VcpuLimitExceeded)"
+        warn "run-instances failed. If the error is VcpuLimitExceeded, return to S1 and request quota."
+        return 1
+      }
+    res_set instance_id "$iid"
+    log "Waiting for instance to become running ..."
+    aws ec2 wait instance-running --instance-ids "$iid" || {
+      phase_set S3_PROVISION failed "instance did not become running before timeout"
+      warn "Timed out waiting for instance running. Check status with aws ec2 describe-instances --instance-ids $iid, then rerun to resume."
+      return 1
+    }
+  fi
+  _record_root_volume_id "$iid"
+
+  # 5) Public address. Production-domain deployments require EIP for stable DNS.
+  local pubip
+  if [ -z "$(res_get eip_id)" ]; then
+    log "Allocating and associating Elastic IP ..."
+    local eip
+    eip=$(aws ec2 allocate-address --domain vpc --query AllocationId --output text) || {
+      phase_set S3_PROVISION failed "failed to allocate EIP"
+      warn "Failed to allocate Elastic IP. Check EIP quota, region, and AWS permissions."
+      return 1
+    }
+    [ -n "$eip" ] && [ "$eip" != "None" ] || {
+      phase_set S3_PROVISION failed "EIP allocation returned no AllocationId"
+      warn "Elastic IP allocation returned no AllocationId. Check AWS response and rerun."
+      return 1
+    }
+    res_set eip_id "$eip"
+    aws ec2 associate-address --instance-id "$iid" --allocation-id "$eip" >/dev/null || {
+      phase_set S3_PROVISION failed "failed to associate EIP"
+      warn "Failed to associate Elastic IP with the instance. Check instance status, EIP quota, and AWS permissions."
+      return 1
+    }
+  fi
+  pubip=$(aws ec2 describe-addresses --allocation-ids "$(res_get eip_id)" \
+            --query 'Addresses[0].PublicIp' --output text) || {
+              phase_set S3_PROVISION failed "failed to read EIP public IP"
+              warn "Failed to read Elastic IP address. Check AllocationId=$(res_get eip_id)."
+              return 1
+            }
+  [ -n "$pubip" ] && [ "$pubip" != "None" ] || {
+    phase_set S3_PROVISION failed "EIP returned no public IP"
+    warn "Elastic IP returned no public IP. Check AWS address allocation status."
+    return 1
+  }
+  res_set public_ip "$pubip"
+  log "Public IP = $pubip; domain = $(state_get domain)"
+
+  if [ "$domain_mode" = "route53" ]; then
+    local route53_rc=0
+    _upsert_route53_record "$domain" "$pubip" || route53_rc=$?
+    [ "$route53_rc" -eq 0 ] || return "$route53_rc"
+  fi
+
+  if [ "$domain_mode" = "user" ] || [ "$domain_mode" = "route53" ]; then
+    _require_user_dns_ready "$domain_mode" "$domain" "$pubip" "$instance_type" || return 2
+  fi
+
+  phase_set S3_PROVISION done "instance=$iid ip=$pubip domain=$(state_get domain)"
+  return 0
+}
+
+_record_root_volume_id() {
+  local iid=$1 volume_id
+  [ -n "$iid" ] || return 0
+  volume_id=$(aws ec2 describe-instances --instance-ids "$iid" \
+    --query 'Reservations[0].Instances[0].BlockDeviceMappings[?Ebs.VolumeId!=`null`].Ebs.VolumeId | [0]' \
+    --output text 2>/dev/null) || return 0
+  [ -n "$volume_id" ] && [ "$volume_id" != "None" ] || return 0
+  res_set root_volume_id "$volume_id"
+}
+
+_upsert_route53_record() {
+  local domain=$1 pubip=$2 zone zone_id zone_name change_file change_id
+  zone=$(_find_or_create_route53_zone "$domain") || {
+    phase_set S3_PROVISION failed "Route53 hosted zone unavailable"
+    warn "DOMAIN_MODE=route53 requires Route53 permission to list or create the hosted zone for $domain."
+    return 1
+  }
+  zone_id=$(printf '%s' "$zone" | cut -f1)
+  zone_name=$(printf '%s' "$zone" | cut -f2)
+  if [ -z "$zone_id" ]; then
+    phase_set S3_PROVISION failed "Route53 hosted zone not found"
+    warn "DOMAIN_MODE=route53 requires the parent domain of $domain to exist in a Route53 hosted zone."
+    return 1
+  fi
+  _guard_route53_a_overwrite "$zone_id" "$domain" "$pubip" || return $?
+
+  log "Route53 upsert: $domain A $pubip (zone=$zone_name)"
+  change_file=$(mktemp)
+  cat > "$change_file" <<EOF
+{
+  "Comment": "p2p-matrix deployment",
+  "Changes": [
+    {
+      "Action": "UPSERT",
+      "ResourceRecordSet": {
+        "Name": "$domain.",
+        "Type": "A",
+        "TTL": 60,
+        "ResourceRecords": [{ "Value": "$pubip" }]
+      }
+    }
+  ]
+}
+EOF
+  local change_file_aws="$change_file"
+  if command -v cygpath >/dev/null 2>&1; then
+    change_file_aws=$(cygpath -w "$change_file")
+  fi
+  change_id=$(aws route53 change-resource-record-sets \
+    --hosted-zone-id "$zone_id" \
+    --change-batch "file://$change_file_aws" \
+    --query 'ChangeInfo.Id' --output text) || {
+      rm -f "$change_file"
+      phase_set S3_PROVISION failed "Route53 upsert failed"
+      return 1
+    }
+  rm -f "$change_file"
+  aws route53 wait resource-record-sets-changed --id "$change_id" || {
+    phase_set S3_PROVISION failed "Route53 change did not complete"
+    return 1
+  }
+  return 0
+}
+
+_route53_existing_a_value() {
+  local zone_id=$1 domain=$2 records name
+  name="${domain}."
+  records=$(aws route53 list-resource-record-sets --hosted-zone-id "$zone_id" --output json 2>/dev/null) || return 0
+  printf '%s\n' "$records" | jq -r --arg name "$name" '
+    .ResourceRecordSets[]?
+    | select(.Name == $name and .Type == "A")
+    | [.ResourceRecords[]?.Value]
+    | join(",")
+  ' | sed -n '1p'
+}
+
+_guard_route53_a_overwrite() {
+  local zone_id=$1 domain=$2 pubip=$3 existing confirmed
+  existing=$(_route53_existing_a_value "$zone_id" "$domain")
+  [ -n "$existing" ] || return 0
+  [ "$existing" = "$pubip" ] && return 0
+
+  res_set route53_existing_a_value "$existing"
+  res_set route53_pending_a_value "$pubip"
+  confirmed=${DIREXIO_CONFIRM_DNS_OVERWRITE:-${CONFIRM_DNS_OVERWRITE:-0}}
+  if [ "$confirmed" = "1" ]; then
+    res_set route53_overwrite_confirmed "true"
+    warn "Route53 A record overwrite confirmed: $domain $existing -> $pubip."
+    return 0
+  fi
+
+  phase_set S3_PROVISION waiting_user "Route53 A record overwrite requires confirmation"
+  warn "Route53 A record overwrite requires confirmation for $domain."
+  warn "Current A record: $existing"
+  warn "New deployment IP: $pubip"
+  warn "If this is intentional, rerun with DIREXIO_CONFIRM_DNS_OVERWRITE=1."
+  return 2
+}
+
+_route53_zone_from_state() {
+  local zone_id zone_name
+  zone_id=$(res_get route53_zone_id)
+  zone_name=$(res_get route53_zone_name)
+  [ -n "$zone_id" ] && [ -n "$zone_name" ] || return 1
+  printf '%s\t%s\n' "$zone_id" "$zone_name"
+}
+
+_record_route53_zone() {
+  local zone_id=$1 zone_name=$2 created=${3:-false} name_servers=${4:-}
+  res_set route53_zone_id "$zone_id"
+  res_set route53_zone_name "${zone_name%.}"
+  if [ -z "$(res_get route53_zone_created_by_deployer)" ] || [ "$created" = "true" ]; then
+    res_set route53_zone_created_by_deployer "$created"
+  fi
+  [ -n "$name_servers" ] && res_set route53_name_servers "$name_servers"
+}
+
+_find_or_create_route53_zone() {
+  local domain=$1 zone zone_id zone_name find_rc
+  if zone=$(_route53_zone_from_state); then
+    printf '%s\n' "$zone"
+    return 0
+  fi
+
+  if zone=$(_find_route53_zone "$domain"); then
+    zone_id=$(printf '%s' "$zone" | cut -f1)
+    zone_name=$(printf '%s' "$zone" | cut -f2)
+    _record_route53_zone "$zone_id" "$zone_name" false
+    printf '%s\n' "$zone"
+    return 0
+  else
+    find_rc=$?
+  fi
+
+  case "$find_rc" in
+    1) _create_route53_zone "$domain" ;;
+    *) return 1 ;;
+  esac
+}
+
+_find_route53_zone() {
+  local domain=$1 best_id="" best_name="" best_len=0 id name clean len zones_json
+  zones_json=$(aws route53 list-hosted-zones --output json) || return 2
+  while IFS=$'\t' read -r id name; do
+    id=${id%$'\r'}
+    name=${name%$'\r'}
+    clean=${name%.}
+    case "$domain" in
+      "$clean"|*."$clean")
+        len=${#clean}
+        if [ "$len" -gt "$best_len" ]; then
+          best_id=${id#/hostedzone/}
+          best_name=$clean
+          best_len=$len
+        fi
+        ;;
+    esac
+  done < <(printf '%s\n' "$zones_json" | jq -r '.HostedZones[] | [.Id, .Name] | @tsv')
+  [ -n "$best_id" ] || return 1
+  printf '%s\t%s\n' "$best_id" "$best_name"
+}
+
+_create_route53_zone() {
+  local domain=$1 zone_name caller created zone_id returned_name name_servers
+  zone_name=${DIREXIO_ROUTE53_ZONE_NAME:-$domain}
+  caller="direxio-$(state_get run_id)-$(date -u +%Y%m%d%H%M%S)"
+  created=$(aws route53 create-hosted-zone \
+    --name "$zone_name" \
+    --caller-reference "$caller" \
+    --output json) || return 1
+  zone_id=$(printf '%s\n' "$created" | jq -r '.HostedZone.Id // empty' | sed 's#^/hostedzone/##')
+  returned_name=$(printf '%s\n' "$created" | jq -r '.HostedZone.Name // empty')
+  name_servers=$(printf '%s\n' "$created" | jq -r '(.DelegationSet.NameServers // []) | join(",")')
+  [ -n "$zone_id" ] && [ -n "$returned_name" ] || return 1
+
+  _record_route53_zone "$zone_id" "${returned_name%.}" true "$name_servers"
+  warn "Created Route53 hosted zone ${returned_name%.} (id=$zone_id). This hosted zone is billable until deleted."
+  if [ -n "$name_servers" ]; then
+    warn "Route53 nameservers: $name_servers"
+    warn "If the domain is registered outside Route53, delegate NS at the registrar before DNS can resolve."
+  fi
+  printf '%s\t%s\n' "$zone_id" "${returned_name%.}"
+}
+
+_require_user_dns_ready() {
+  local domain_mode=$1 domain=$2 pubip=$3 instance_type=$4
+  if [ "$(state_get dns_ready)" = "true" ]; then
+    domain_resolves_to_ip "$domain" "$pubip" && return 0
+    warn "state has dns_ready=true, but current DNS does not point to $pubip. Continuing to wait to avoid early certificate issuance."
+    state_set_raw dns_ready 'false'
+  fi
+  if domain_resolves_to_ip "$domain" "$pubip"; then
+    ok "DNS resolves to $pubip: $domain"
+    state_set_raw dns_ready 'true'
+    return 0
+  fi
+  if [ "${DNS_READY:-0}" = "1" ] || [ "${CONFIRM_DNS_READY:-0}" = "1" ]; then
+    if domain_resolves_to_ip "$domain" "$pubip"; then
+      state_set_raw dns_ready 'true'
+      return 0
+    fi
+    warn "DNS_READY is set, but $domain does not resolve to ${pubip} yet. Waiting to avoid Caddy/Let's Encrypt racing DNS."
+  fi
+
+  if [ "$domain_mode" = "route53" ]; then
+    warn "Route53 A record was submitted, but $domain does not resolve to ${pubip} yet."
+    warn "This is usually DNS propagation delay; rerun later to continue."
+  else
+    warn "Update DNS so $domain has an A record pointing to this EC2 public IP:"
+    warn "  $domain  A  $pubip"
+    warn "Use a subdomain such as __DOMAIN__. If DNS is on Cloudflare, set it to DNS only; do not enable proxying."
+  fi
+  warn "Use this command to confirm DNS now points at the new IP:"
+  warn "  dig +short $domain"
+  warn "Continue to S4 only after DNS is active, otherwise Caddy cannot issue the Let's Encrypt certificate."
+
+  if [ "$domain_mode" = "user" ] && [ -t 0 ]; then
+    printf "Have you updated the DNS A record and waited for propagation? [y/N] " >&2
+    local ans
+    read -r ans
+    if is_yes "$ans"; then
+      if domain_resolves_to_ip "$domain" "$pubip"; then
+        state_set_raw dns_ready 'true'
+        return 0
+      fi
+      warn "$domain still does not resolve to $pubip; confirmation alone is not enough to continue."
+    fi
+  fi
+
+  phase_set S3_PROVISION waiting_user "waiting for DNS A record $domain -> $pubip"
+  warn "After DNS is ready, rerun:"
+  warn "  DOMAIN=$domain DOMAIN_MODE=$domain_mode CONFIRM_DOMAIN_BINDING=1 INSTANCE_TYPE=$instance_type bash scripts/orchestrate.sh"
+  return 2
+}

package/scripts/phases/s4_bootstrap_stack.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# S4 BOOTSTRAP_STACK - cloud-init installs Docker, starts the stack, and gets TLS.
+# The local agent polls https://<domain>/healthz until it returns 200.
+
+run_phase() {
+  phase_set S4_BOOTSTRAP_STACK polling "waiting for instance bootstrap and services"
+  local domain pubip keyfile curl_connect_timeout curl_max_time
+  domain=$(state_get domain)
+  pubip=$(res_get public_ip)
+  keyfile=$(res_get key_file)
+  curl_connect_timeout=${HEALTH_CURL_CONNECT_TIMEOUT:-10}
+  curl_max_time=${HEALTH_CURL_MAX_TIME:-20}
+
+  log "Waiting for bootstrap (install Docker -> start postgres/message-server/caddy/coturn -> issue Let's Encrypt certificate)..."
+  log "First image pull and certificate issuance usually take 5-10 minutes. Checking https://$domain/healthz every ${HEALTH_POLL_INTERVAL:-10}s (curl connect timeout ${curl_connect_timeout}s, max ${curl_max_time}s) ..."
+
+  if poll_until "health check https://$domain/healthz == 200" \
+       "${HEALTH_POLL_INTERVAL:-10}" "${HEALTH_POLL_MAX:-90}" _healthz_ok "$domain"; then
+    phase_set S4_BOOTSTRAP_STACK done "healthz 200 @ https://$domain"
+    return 0
+  fi
+
+  phase_set S4_BOOTSTRAP_STACK failed "healthz did not return 200 before timeout"
+  warn "Health check timed out. Inspect cloud-init logs over SSH:"
+  warn "  ssh -i $keyfile ubuntu@$pubip 'sudo tail -n 80 /var/log/cloud-init-output.log; cd /opt/p2p && sudo docker compose ps && sudo docker compose logs message-server --tail=80'"
+  warn "See references/troubleshooting.md for targeted troubleshooting."
+  return 1
+}
+
+_healthz_ok() {
+  local domain=$1 pubip curl_args
+  pubip=$(res_get public_ip)
+  curl_args=(-skf --connect-timeout "${HEALTH_CURL_CONNECT_TIMEOUT:-10}" --max-time "${HEALTH_CURL_MAX_TIME:-20}")
+  if [ -n "$pubip" ]; then
+    curl "${curl_args[@]}" --resolve "$domain:443:$pubip" "https://$domain/healthz" >/dev/null 2>&1 && return 0
+  fi
+  curl "${curl_args[@]}" "https://$domain/healthz" >/dev/null 2>&1
+}