validate.func

#!/usr/bin/env bash
# Copyright (c) 2021-2026 community-scripts ORG
# License: MIT | https://raw.githubusercontent.com/community-scripts/core/main/LICENSE

# ==============================================================================
# BUILD-UI/VALIDATE.FUNC - INPUT VALIDATION AND IP RANGE HELPERS
# ==============================================================================
# Part of the build UI. Load ui/build-ui.func -- it sources every part --
# rather than this file directly; the split is for maintenance only and no
# function name or behaviour changed with it.
# ==============================================================================

[[ -n "${_BUILD_UI_VALIDATE_LOADED:-}" ]] && return 0
_BUILD_UI_VALIDATE_LOADED=1

# ==============================================================================
# SECTION 3: CONTAINER SETUP UTILITIES
# ==============================================================================

# ------------------------------------------------------------------------------
# get_current_ip()
#
# - Returns current container IP depending on OS type
# - Debian/Ubuntu: uses `hostname -I`
# - Alpine: parses eth0 via `ip -4 addr` or `ip -6 addr`
# - Supports IPv6-only environments as fallback
# - Returns "Unknown" if OS type cannot be determined
# ------------------------------------------------------------------------------
get_current_ip() {
  CURRENT_IP=""
  if [ -f /etc/os-release ]; then
    # Check for Debian/Ubuntu (uses hostname -I)
    if grep -qE 'ID=debian|ID=ubuntu' /etc/os-release; then
      # Try IPv4 first. No match is not an error: under pipefail it ended the
      # update before the IPv6 fallback was reached.
      CURRENT_IP=$(hostname -I 2>/dev/null | tr ' ' '\n' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$' | head -n1 || true)
      # Fallback to IPv6 if no IPv4
      if [[ -z "$CURRENT_IP" ]]; then
        CURRENT_IP=$(hostname -I 2>/dev/null | tr ' ' '\n' | grep -E ':' | head -n1 || true)
      fi
    # Check for Alpine (uses ip command)
    elif grep -q 'ID=alpine' /etc/os-release; then
      # Try IPv4 first
      CURRENT_IP=$(ip -4 addr show eth0 2>/dev/null | awk '/inet / {print $2}' | cut -d/ -f1 | head -n 1 || true)
      # Fallback to IPv6 if no IPv4
      if [[ -z "$CURRENT_IP" ]]; then
        CURRENT_IP=$(ip -6 addr show eth0 scope global 2>/dev/null | awk '/inet6 / {print $2}' | cut -d/ -f1 | head -n 1 || true)
      fi
    else
      CURRENT_IP="Unknown"
    fi
  fi
  echo "$CURRENT_IP"
}

# ------------------------------------------------------------------------------
# update_motd_ip()
#
# - Updates /etc/motd with current container IP
# - Removes old IP entries to avoid duplicates
# ------------------------------------------------------------------------------
update_motd_ip() {
  MOTD_FILE="/etc/motd"

  # install.func declares this as a `local`, and an update never goes through
  # install.func at all -- read here as a global it ended the update with
  # "PROFILE_FILE: unbound variable". A constant, so name it like MOTD_FILE.
  local profile_file="${PROFILE_FILE:-/etc/profile.d/00_lxc-details.sh}"

  # Only touch /etc/motd when it is the one motd_ssh wrote. A container created
  # before that still carries the distribution's own file, and appending to it
  # left a stray IP line under that boilerplate. The profile branch below has
  # always checked whose file it is; this one never did.
  if [ -f "$MOTD_FILE" ] && grep -q "LXC Container" "$MOTD_FILE" 2>/dev/null; then
    # Remove existing IP Address lines to prevent duplication
    sed -i '/IP Address:/d' "$MOTD_FILE"

    IP=$(get_current_ip)
    # Add the new IP address
    echo -e "${TAB}${NETWORK}${YW} IP Address: ${GN}${IP}${CL}" >>"$MOTD_FILE"
  fi

  # Update dynamic LXC details profile if values changed (e.g., after OS upgrade)
  # Only update if file exists and is from community-scripts
  if [ -f "$profile_file" ] && grep -q "community-scripts" "$profile_file" 2>/dev/null; then
    # Legacy header: re-derives the app name by grepping /usr/bin/update's own
    # text, which breaks once migrate_update_entrypoint parameterizes that URL.
    # Collapse it to a static line using the name already resolved there.
    if grep -q 'APPL_NAME' "$profile_file" 2>/dev/null && grep -q 'LXC Container' "$profile_file" 2>/dev/null; then
      local legacy_name
      legacy_name="$(grep -m1 '^export UPDATE_SCRIPT_NAME=' /usr/bin/update 2>/dev/null | cut -d'"' -f2)"
      if [[ "$legacy_name" =~ ^[a-zA-Z0-9._-]+$ ]]; then
        local display_name="${legacy_name^}"
        # Raw bytes, not $YW/$CL: unset in a login shell on affected containers.
        local tmp_header
        tmp_header="$(mktemp)"
        printf 'echo -e ""\necho -e "\033[1m%s LXC Container\033[m"\n' "$display_name" >"$tmp_header"
        sed -i "/APPL_NAME/,/LXC Container/{
          /LXC Container/r $tmp_header
          d
        }" "$profile_file"
        rm -f "$tmp_header"
      fi
    fi

    # Get current values
    local current_os="$(grep ^NAME /etc/os-release | cut -d= -f2 | tr -d '"') - Version: $(grep ^VERSION_ID /etc/os-release | cut -d= -f2 | tr -d '"')"
    local current_hostname="$(hostname 2>/dev/null || uname -n)"
    # get_current_ip, not `hostname -I`: BusyBox's hostname has no -I, so on
    # Alpine this aborted the update with "unrecognized option: I". The helper
    # a few lines above already handles that and is used for the MOTD line.
    local current_ip="$(get_current_ip)"

    # $GN/$CL are unset in a login shell, so a line using them never colors.
    # The staleness checks below only compare the value text, so a line with a
    # current value but a dead placeholder is never revisited; force it here.
    local esc dead_color_os dead_color_hostname dead_color_ip
    esc=$'\033'
    grep -qE 'OS:.*\$\{GN\}' "$profile_file" 2>/dev/null && dead_color_os=1
    grep -qE 'Hostname:.*\$\{GN\}' "$profile_file" 2>/dev/null && dead_color_hostname=1
    grep -qE 'IP Address:.*\$\{GN\}' "$profile_file" 2>/dev/null && dead_color_ip=1

    # Update only if values actually changed (or the color placeholder is dead)
    if [[ -n "${dead_color_os:-}" ]] || ! grep -q "OS:.*$current_os" "$profile_file" 2>/dev/null; then
      sed -i "s|OS:.*|OS: ${esc}[1;92m$current_os${esc}[m\\\"|" "$profile_file"
    fi
    if [[ -n "${dead_color_hostname:-}" ]] || ! grep -q "Hostname:.*$current_hostname" "$profile_file" 2>/dev/null; then
      sed -i "s|Hostname:.*|Hostname: ${esc}[1;92m$current_hostname${esc}[m\\\"|" "$profile_file"
    fi
    # motd_ssh writes the IP line as a command substitution so it follows the
    # container. Rewriting it here replaced that with whatever the address was
    # on the day of the first update and it never moved again -- and since the
    # literal address is then never found by the grep above, the substitution
    # fired on every run. Leave a line that computes its own value alone.
    if grep -q 'IP Address:.*\$(' "$profile_file" 2>/dev/null; then
      :
    elif [[ -n "${dead_color_ip:-}" ]] || ! grep -q "IP Address:.*$current_ip" "$profile_file" 2>/dev/null; then
      sed -i "s|IP Address:.*|IP Address: ${esc}[1;92m$current_ip${esc}[m\\\"|" "$profile_file"
    fi
  fi
}

# ------------------------------------------------------------------------------
# install_ssh_keys_into_ct()
#
# - Installs SSH keys into container root account if SSH is enabled
# - Uses pct push or direct input to authorized_keys
# - Supports both SSH_KEYS_FILE (from advanced settings) and SSH_AUTHORIZED_KEY (from user defaults)
# - Falls back to warning if no keys provided
# ------------------------------------------------------------------------------
install_ssh_keys_into_ct() {
  [[ "${SSH:-no}" != "yes" ]] && return 0

  # Ensure SSH_KEYS_FILE is defined (may not be set if advanced_settings was skipped)
  : "${SSH_KEYS_FILE:=}"

  # If SSH_KEYS_FILE doesn't exist but SSH_AUTHORIZED_KEY is set (from user defaults),
  # create a temporary SSH_KEYS_FILE with the key
  if [[ -z "$SSH_KEYS_FILE" || ! -s "$SSH_KEYS_FILE" ]] && [[ -n "${SSH_AUTHORIZED_KEY:-}" ]]; then
    SSH_KEYS_FILE="$(mktemp)"
    printf '%s\n' "$SSH_AUTHORIZED_KEY" >"$SSH_KEYS_FILE"
  fi

  if [[ -n "$SSH_KEYS_FILE" && -s "$SSH_KEYS_FILE" ]]; then
    msg_info "Installing selected SSH keys into CT ${CTID}"
    pct exec "$CTID" -- sh -c 'mkdir -p /root/.ssh && chmod 700 /root/.ssh' || {
      msg_error "prepare /root/.ssh failed"
      return 1
    }
    pct push "$CTID" "$SSH_KEYS_FILE" /root/.ssh/authorized_keys >/dev/null 2>&1 ||
      pct exec "$CTID" -- sh -c "cat > /root/.ssh/authorized_keys" <"$SSH_KEYS_FILE" || {
      msg_error "write authorized_keys failed"
      return 1
    }
    pct exec "$CTID" -- sh -c 'chmod 600 /root/.ssh/authorized_keys' || true
    msg_ok "Installed SSH keys into CT ${CTID}"
    return 0
  fi

  # Fallback
  msg_warn "No SSH keys to install (skipping)."
  return 0
}

# _vmid_config_exists <id> - a VM or container config for the ID on any node
_vmid_config_exists() {
  local f
  for f in /etc/pve/nodes/*/qemu-server/"$1".conf /etc/pve/nodes/*/lxc/"$1".conf \
    /etc/pve/qemu-server/"$1".conf /etc/pve/lxc/"$1".conf; do
    [[ -f "$f" ]] && return 0
  done
  return 1
}

# ------------------------------------------------------------------------------
# validate_container_id()
#
# - Validates if a container ID is available for use
# - Checks if ID is already used by VM or LXC container
# - Checks if ID is used in LVM logical volumes
# - Returns 0 if ID is available, 1 if already in use
# ------------------------------------------------------------------------------
validate_container_id() {
  local ctid="$1"

  # Check if ID is numeric
  if ! [[ "$ctid" =~ ^[0-9]+$ ]]; then
    return 1
  fi

  # /etc/pve/qemu-server and /etc/pve/lxc only point into this node's own
  # directory; /etc/pve/nodes holds every node's guests. pvesh's
  # /cluster/resources says the same in about a second, and the ID search
  # asks once per ID it tries, so it is only the fallback without pmxcfs.
  if [[ -d "/etc/pve/nodes" ]]; then
    _vmid_config_exists "$ctid" && return 1
  elif command -v pvesh &>/dev/null; then
    local cluster_ids
    cluster_ids=$(pvesh get /cluster/resources --type vm --output-format json 2>/dev/null |
      grep -oP '"vmid":\s*\K[0-9]+' 2>/dev/null || true)
    if [[ -n "$cluster_ids" ]] && echo "$cluster_ids" | grep -qw "$ctid"; then
      return 1
    fi
  fi

  # Check if ID is used in LVM logical volumes
  if lvs --noheadings -o lv_name 2>/dev/null | grep -qE "(^|[-_])${ctid}($|[-_])"; then
    return 1
  fi

  return 0
}

# ------------------------------------------------------------------------------
# get_valid_container_id()
#
# - Returns a valid, unused container ID
# - If provided ID is valid, returns it
# - Otherwise increments from suggested ID until a free one is found
# - Calls validate_container_id() to check availability
# ------------------------------------------------------------------------------
get_valid_container_id() {
  local suggested_id="${1:-$(pvesh get /cluster/nextid 2>/dev/null || echo 100)}"

  # A failed pvesh used to leave this empty, and $((empty + 1)) is 1 -- so the
  # search started at 1 and walked up through every ID on the host.
  if ! [[ "$suggested_id" =~ ^[0-9]+$ ]]; then
    suggested_id=$(pvesh get /cluster/nextid 2>/dev/null || echo 100)
  fi

  # Bounded, because the loop above had no exit. Exit code 109 is documented
  # for exactly this and was never reachable.
  local max_attempts=1000 attempts=0
  while ! validate_container_id "$suggested_id"; do
    suggested_id=$((suggested_id + 1))
    attempts=$((attempts + 1))
    if [[ $attempts -ge $max_attempts ]]; then
      msg_error "Could not find an available container ID after $max_attempts attempts"
      exit 109
    fi
  done

  echo "$suggested_id"
}

# ------------------------------------------------------------------------------
# validate_hostname()
#
# - Validates hostname/FQDN according to RFC 1123/952
# - Checks total length (max 253 characters for FQDN)
# - Validates each label (max 63 chars, alphanumeric + hyphens)
# - Returns 0 if valid, 1 if invalid
# ------------------------------------------------------------------------------
validate_hostname() {
  local hostname="$1"

  # Check total length (max 253 for FQDN)
  if [[ ${#hostname} -gt 253 ]] || [[ -z "$hostname" ]]; then
    return 1
  fi

  # Split by dots and validate each label
  local IFS='.'
  read -ra labels <<<"$hostname"
  for label in "${labels[@]}"; do
    # Each label: 1-63 chars, alphanumeric, hyphens allowed (not at start/end)
    if [[ -z "$label" ]] || [[ ${#label} -gt 63 ]]; then
      return 1
    fi
    if [[ ! "$label" =~ ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ ]] && [[ ! "$label" =~ ^[a-z0-9]$ ]]; then
      return 1
    fi
  done

  return 0
}




# ------------------------------------------------------------------------------
# validate_ipv6_address()
#
# - Validates IPv6 address with optional CIDR notation
# - Supports compressed (::) and full notation
# - Empty value is allowed
# - Returns 0 if valid, 1 if invalid
# ------------------------------------------------------------------------------
validate_ipv6_address() {
  local ipv6="$1"
  [[ -z "$ipv6" ]] && return 0

  # Extract address and CIDR
  local addr="${ipv6%%/*}"
  local cidr="${ipv6##*/}"

  # Validate CIDR if present (1-128)
  if [[ "$ipv6" == */* ]]; then
    if ! [[ "$cidr" =~ ^[0-9]+$ ]] || ((cidr < 1 || cidr > 128)); then
      return 1
    fi
  fi

  # Basic IPv6 validation - check for valid characters and structure
  # Must contain only hex digits and colons
  if [[ ! "$addr" =~ ^[0-9a-fA-F:]+$ ]]; then
    return 1
  fi

  # Must contain at least one colon
  if [[ ! "$addr" == *:* ]]; then
    return 1
  fi

  # Check for valid double-colon usage (only one :: allowed)
  if [[ "$addr" == *::*::* ]]; then
    return 1
  fi

  # Check that no segment exceeds 4 hex chars
  local IFS=':'
  local -a segments
  read -ra segments <<<"$addr"
  for seg in "${segments[@]}"; do
    if [[ ${#seg} -gt 4 ]]; then
      return 1
    fi
  done

  return 0
}

# ------------------------------------------------------------------------------
# validate_bridge()
#
# - Validates that network bridge exists and is active
# - Returns 0 if valid, 1 if invalid
# ------------------------------------------------------------------------------
validate_bridge() {
  local bridge="$1"
  [[ -z "$bridge" ]] && return 1

  # Check if bridge interface exists
  if ! ip link show "$bridge" &>/dev/null; then
    return 1
  fi

  return 0
}

# ------------------------------------------------------------------------------
# validate_sdn_vnet()
#
# - Validates an SDN vnet name against the cluster configuration
# - Checks /etc/pve/sdn/vnets.cfg first, then falls back to pvesh when present
# ------------------------------------------------------------------------------
validate_sdn_vnet() {
  local vnet="$1"
  [[ -z "$vnet" ]] && return 1
  [[ -f /etc/pve/sdn/vnets.cfg ]] && grep -qE "^vnet:[[:space:]]*${vnet}([[:space:]]|$)" /etc/pve/sdn/vnets.cfg && return 0
  command -v pvesh &>/dev/null && pvesh get "/cluster/sdn/vnets/${vnet}" &>/dev/null && return 0
  return 1
}

# ------------------------------------------------------------------------------
# validate_gateway_in_subnet()
#
# - Validates that gateway IP is in the same subnet as static IP
# - Arguments: static_ip (with CIDR), gateway_ip
# - Returns 0 if valid, 1 if invalid
# ------------------------------------------------------------------------------
validate_gateway_in_subnet() {
  local static_ip="$1"
  local gateway="$2"

  [[ -z "$static_ip" || -z "$gateway" ]] && return 0

  # Extract IP and CIDR
  local ip="${static_ip%%/*}"
  local cidr="${static_ip##*/}"

  # /31 and /32 have no usable subnet, so an off-subnet gateway is normal there.
  ((cidr >= 31)) && return 0

  # Convert CIDR to netmask bits
  local mask=$((0xFFFFFFFF << (32 - cidr) & 0xFFFFFFFF))

  # Convert IPs to integers
  local IFS='.'
  read -r i1 i2 i3 i4 <<<"$ip"
  read -r g1 g2 g3 g4 <<<"$gateway"

  local ip_int=$(((i1 << 24) + (i2 << 16) + (i3 << 8) + i4))
  local gw_int=$(((g1 << 24) + (g2 << 16) + (g3 << 8) + g4))

  # Check if both are in same network
  if (((ip_int & mask) != (gw_int & mask))); then
    return 1
  fi

  return 0
}

# ------------------------------------------------------------------------------
# validate_ip_address()
#
# - Validates IPv4 address with CIDR notation
# - Checks each octet is 0-255
# - Checks CIDR is 1-32
# - Returns 0 if valid, 1 if invalid
# ------------------------------------------------------------------------------
validate_ip_address() {
  local ip="$1"
  [[ -z "$ip" ]] && return 1

  # Check format with CIDR
  if [[ ! "$ip" =~ ^([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})/([0-9]{1,2})$ ]]; then
    return 1
  fi

  local o1="${BASH_REMATCH[1]}"
  local o2="${BASH_REMATCH[2]}"
  local o3="${BASH_REMATCH[3]}"
  local o4="${BASH_REMATCH[4]}"
  local cidr="${BASH_REMATCH[5]}"

  # Validate octets (0-255)
  for octet in "$o1" "$o2" "$o3" "$o4"; do
    if ((octet > 255)); then
      return 1
    fi
  done

  # Validate CIDR (1-32)
  if ((cidr < 1 || cidr > 32)); then
    return 1
  fi

  return 0
}

# ------------------------------------------------------------------------------
# validate_gateway_ip()
#
# - Validates gateway IPv4 address (without CIDR)
# - Checks each octet is 0-255
# - Returns 0 if valid, 1 if invalid
# ------------------------------------------------------------------------------
validate_gateway_ip() {
  local ip="$1"
  [[ -z "$ip" ]] && return 0

  # Check format without CIDR
  if [[ ! "$ip" =~ ^([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})$ ]]; then
    return 1
  fi

  local o1="${BASH_REMATCH[1]}"
  local o2="${BASH_REMATCH[2]}"
  local o3="${BASH_REMATCH[3]}"
  local o4="${BASH_REMATCH[4]}"

  # Validate octets (0-255)
  for octet in "$o1" "$o2" "$o3" "$o4"; do
    if ((octet > 255)); then
      return 1
    fi
  done

  return 0
}

# ------------------------------------------------------------------------------
# validate_timezone()
#
# - Validates a timezone the way pct does: UTC or a zone.tab name, or an alias
#   of one (see pct_timezone)
# - Empty value or "host" is allowed
# - Returns 0 if valid, 1 if invalid
# ------------------------------------------------------------------------------
validate_timezone() {
  local tz="$1"
  [[ -z "$tz" || "$tz" == "host" ]] && return 0
  [[ -n "$(pct_timezone "$tz")" ]]
}

_in_zone_tab() {
  awk -F'\t' -v z="$1" '!/^#/ && $3 == z {f = 1} END {exit !f}' /usr/share/zoneinfo/zone.tab 2>/dev/null
}

# ------------------------------------------------------------------------------
# pct_timezone()
#
# - Prints a zone the way pct accepts it: UTC or a name from zone.tab
# - "host" is resolved here instead of by pct, whose timedatectl call fails on
#   some hosts
# - Aliases such as US/Eastern resolve to their canonical zone, through the
#   zoneinfo link or, with tzdata-legacy not installed, through tzdata.zi
# - Prints nothing for a zone pct cannot take (Etc/GMT+1), so the container
#   keeps the template's own setting
# ------------------------------------------------------------------------------
pct_timezone() {
  local tz="$1" real
  if [[ "$tz" == "host" ]]; then
    tz="$(cat /etc/timezone 2>/dev/null)"
    if [[ -z "$tz" ]]; then
      tz="$(readlink -f /etc/localtime 2>/dev/null)"
      tz="${tz#/usr/share/zoneinfo/}"
    fi
  fi
  [[ -n "$tz" ]] || return 0
  case "$tz" in
  UTC | Etc/UTC | Etc/UCT | Etc/Universal | Etc/Zulu | Universal | Zulu | UCT)
    echo "UTC"
    return 0
    ;;
  esac
  if _in_zone_tab "$tz"; then
    echo "$tz"
    return 0
  fi
  real="$(readlink -f "/usr/share/zoneinfo/$tz" 2>/dev/null)"
  real="${real#/usr/share/zoneinfo/}"
  if [[ "$real" != "$tz" ]] && _in_zone_tab "$real"; then
    echo "$real"
    return 0
  fi
  real="$(awk -v z="$tz" '$1 == "L" && $3 == z {print $2; exit}' /usr/share/zoneinfo/tzdata.zi 2>/dev/null)"
  if [[ -n "$real" ]] && _in_zone_tab "$real"; then
    echo "$real"
  fi
  return 0
}

# ------------------------------------------------------------------------------
# validate_ram_size()
#
# - RAM in MiB, at least 128: below that a Debian container cannot install
#   anything, and the value is nearly always GiB typed into a MiB field
# ------------------------------------------------------------------------------
validate_ram_size() {
  [[ "$1" =~ ^[1-9][0-9]*$ ]] && (($1 >= 128))
}

# ------------------------------------------------------------------------------
# validate_nameservers()
#
# - IPv4/IPv6 addresses separated by spaces or commas, as pct's nameserver
#   takes; host names are not accepted there
# - Empty value is allowed
# ------------------------------------------------------------------------------
validate_nameservers() {
  local ns
  local -a list
  read -ra list <<<"${1//[,;]/ }"
  for ns in "${list[@]}"; do
    validate_gateway_ip "$ns" && continue
    [[ "$ns" != */* ]] && validate_ipv6_address "$ns" && continue
    return 1
  done
}

# ------------------------------------------------------------------------------
# validate_searchdomain()
#
# - DNS names separated by spaces or commas, e.g. example.com
# - Empty value is allowed
# ------------------------------------------------------------------------------
validate_searchdomain() {
  local d label='[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?'
  local -a list
  read -ra list <<<"${1//[,;]/ }"
  for d in "${list[@]}"; do
    [[ "$d" =~ ^(${label}\.)*${label}\.?$ ]] || return 1
  done
}

# ------------------------------------------------------------------------------
# validate_mount_fs()
#
# - Filesystem types a container may mount (feature mount=), e.g. nfs, cifs
# - Paths are not filesystem types: sharing a host directory is a bind mount
# - Empty value is allowed
# ------------------------------------------------------------------------------
validate_mount_fs() {
  local fs
  local -a list
  read -ra list <<<"${1//[,;]/ }"
  for fs in "${list[@]}"; do
    [[ "$fs" =~ ^[a-z0-9_]+$ ]] || return 1
  done
}

# ------------------------------------------------------------------------------
# validate_tags()
#
# - Validates Proxmox tags format
# - Only alphanumeric, hyphens, underscores, and semicolons allowed
# - Empty value is allowed
# - Returns 0 if valid, 1 if invalid
# ------------------------------------------------------------------------------
validate_tags() {
  local tags="$1"
  [[ -z "$tags" ]] && return 0

  # Tags can only contain alphanumeric, -, _, and ; (separator)
  if [[ ! "$tags" =~ ^[a-zA-Z0-9_\;-]+$ ]]; then
    return 1
  fi

  return 0
}

# ------------------------------------------------------------------------------
# find_host_ssh_keys()
#
# - Scans system for available SSH keys
# - Supports defaults (~/.ssh, /etc/ssh/authorized_keys)
# - Returns list of files containing valid SSH public keys
# - Sets FOUND_HOST_KEY_COUNT to number of keys found
# ------------------------------------------------------------------------------
find_host_ssh_keys() {
  local re='(ssh-(rsa|ed25519)|ecdsa-sha2-nistp256|sk-(ssh-ed25519|ecdsa-sha2-nistp256))'
  local -a files=() cand=()
  local g="${var_ssh_import_glob:-}"
  local total=0 f base c

  shopt -s nullglob
  if [[ -n "$g" ]]; then
    for pat in $g; do cand+=($pat); done
  else
    cand+=(/root/.ssh/authorized_keys /root/.ssh/authorized_keys2)
    cand+=(/root/.ssh/*.pub)
    cand+=(/etc/ssh/authorized_keys /etc/ssh/authorized_keys.d/*)
  fi
  shopt -u nullglob

  for f in "${cand[@]}"; do
    [[ -f "$f" && -r "$f" ]] || continue
    base="$(basename -- "$f")"
    case "$base" in
    known_hosts | known_hosts.* | config) continue ;;
    id_*) [[ "$f" != *.pub ]] && continue ;;
    esac

    # CRLF safe check for host keys
    c=$(tr -d '\r' <"$f" | awk '
      /^[[:space:]]*#/ {next}
      /^[[:space:]]*$/ {next}
      {print}
    ' | grep -E -c '"$re"' || true)

    if ((c > 0)); then
      files+=("$f")
      total=$((total + c))
    fi
  done

  # Fallback to /root/.ssh/authorized_keys
  if ((${#files[@]} == 0)) && [[ -r /root/.ssh/authorized_keys ]]; then
    if grep -E -q "$re" /root/.ssh/authorized_keys; then
      files+=(/root/.ssh/authorized_keys)
      total=$((total + $(grep -E -c "$re" /root/.ssh/authorized_keys || echo 0)))
    fi
  fi

  FOUND_HOST_KEY_COUNT="$total"
  (
    IFS=:
    echo "${files[*]}"
  )
}

# ==============================================================================
# SECTION 3B: IP RANGE SCANNING
# ==============================================================================

# ------------------------------------------------------------------------------
# ip_to_int() / int_to_ip()
#
# - Converts IP address to integer and vice versa for range iteration
# ------------------------------------------------------------------------------
ip_to_int() {
  local IFS=.
  read -r i1 i2 i3 i4 <<<"$1"
  echo $(((i1 << 24) + (i2 << 16) + (i3 << 8) + i4))
}

int_to_ip() {
  local ip=$1
  echo "$(((ip >> 24) & 0xFF)).$(((ip >> 16) & 0xFF)).$(((ip >> 8) & 0xFF)).$((ip & 0xFF))"
}

# ------------------------------------------------------------------------------
# resolve_ip_from_range()
#
# - Takes an IP range in format "10.0.0.1/24-10.0.0.10/24"
# - Pings each IP in the range to find the first available one
# - Returns the first free IP with CIDR notation
# - Sets NET_RESOLVED to the resolved IP or empty on failure
# ------------------------------------------------------------------------------
resolve_ip_from_range() {
  local range="$1"
  local ip_cidr_regex='^([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})/([0-9]{1,2})$'
  local ip_start ip_end

  # Parse range: "10.0.0.1/24-10.0.0.10/24"
  ip_start="${range%%-*}"
  ip_end="${range##*-}"

  if [[ ! "$ip_start" =~ $ip_cidr_regex ]] || [[ ! "$ip_end" =~ $ip_cidr_regex ]]; then
    NET_RESOLVED=""
    return 1
  fi

  local ip1="${ip_start%%/*}"
  local ip2="${ip_end%%/*}"
  local cidr="${ip_start##*/}"

  local start_int=$(ip_to_int "$ip1")
  local end_int=$(ip_to_int "$ip2")

  for ((ip_int = start_int; ip_int <= end_int; ip_int++)); do
    local ip=$(int_to_ip $ip_int)
    msg_info "Checking IP: $ip"
    if ! ping -c 1 -W 1 "$ip" >/dev/null 2>&1; then
      NET_RESOLVED="$ip/$cidr"
      msg_ok "Found free IP: ${BGN}$NET_RESOLVED${CL}"
      return 0
    fi
  done

  NET_RESOLVED=""
  msg_error "No free IP found in range $range"
  return 1
}

# ------------------------------------------------------------------------------
# is_ip_range()
#
# - Checks if a string is an IP range (contains - and looks like IP/CIDR)
# - Returns 0 if it's a range, 1 otherwise
# ------------------------------------------------------------------------------
is_ip_range() {
  local value="$1"
  local ip_start ip_end
  if [[ "$value" == *-* ]] && [[ "$value" != "dhcp" ]]; then
    local ip_cidr_regex='^([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})/([0-9]{1,2})$'
    ip_start="${value%%-*}"
    ip_end="${value##*-}"
    if [[ "$ip_start" =~ $ip_cidr_regex ]] && [[ "$ip_end" =~ $ip_cidr_regex ]]; then
      return 0
    fi
  fi
  return 1
}