refactor: letsencrypt implicit location discovery (#2525)

* chore: Extract letsencrypt logic into methods

This allows other scripts to share the functionality to discover the correct letsencrypt folder from the 3 possible locations (where specific order is important).

As these methods should now return a string value, the `return 1` after a panic is now dropped.

* chore: Update comments

The todo is resolved with this PR, `_setup_ssl` will be called by both cert conditional statements with purpose for each better documented to maintainers at the start of the logic block.

* refactor: Defer most logic to helper/ssl.sh

The loop is no longer required, extraction is delegated to `_setup_ssl` now.

For the change event prevention, we retrieve the relevant FQDN via the new helper method, beyond that it's just indentation diff.

`check-for-changes.sh` adjusted to allow locally scoped var declarations by wrapping a function. Presently no loop control flow is needed so this seems fine. Made it clear that `CHANGED` is local and `CHKSUM_FILE` is not.

Panic scope doesn't require `SSL_TYPE` for context, it's clearly`letsencrypt`.

* fix: Correctly match wildcard results

Now that the service configs are properly updated, when the services restart they will return a cert with the SAN `DNS:*.example.test`,  which is valid for `mail.example.test`, however the test function did not properly account for this in the regexp query.

Resolved by truncating the left-most DNS label from FQDN and adding a third check to match a returned wildcard DNS result.

Extracted out the common logic to create the regexp query and renamed the methods to communicate more clearly that they check the FQDN is supported, not necessarily explicitly listed by the cert.

* tests(letsencrypt): Enable remaining tests

These will now pass. Adjusted comments accordingly.

Added an additional test on a fake FQDN that should still be valid to a wildcard cert (SNI validation in a proper setup would reject the connection afterwards).

Co-authored-by: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com>

target/scripts/helpers/ssl.sh

@@ -185,38 +185,10 @@ function _setup_ssl
 
       _traefik_support
 
-      # letsencrypt folders and files mounted in /etc/letsencrypt
-      local LETSENCRYPT_DOMAIN
-      local LETSENCRYPT_KEY
-
-      # Identify a valid letsencrypt FQDN folder to use.
-      if [[ -n ${SSL_DOMAIN} ]] && [[ -e /etc/letsencrypt/live/$(_strip_wildcard_prefix "${SSL_DOMAIN}")/fullchain.pem ]]
-      then
-        LETSENCRYPT_DOMAIN=$(_strip_wildcard_prefix "${SSL_DOMAIN}")
-      elif [[ -e /etc/letsencrypt/live/${HOSTNAME}/fullchain.pem ]]
-      then
-        LETSENCRYPT_DOMAIN=${HOSTNAME}
-      elif [[ -e /etc/letsencrypt/live/${DOMAINNAME}/fullchain.pem ]]
-      then
-        LETSENCRYPT_DOMAIN=${DOMAINNAME}
-      else
-        _log 'warn' "Cannot find a valid DOMAIN for '/etc/letsencrypt/live/<DOMAIN>/', tried: '${SSL_DOMAIN}', '${HOSTNAME}', '${DOMAINNAME}'"
-        dms_panic__misconfigured 'LETSENCRYPT_DOMAIN' "${SCOPE_SSL_TYPE}"
-        return 1
-      fi
-
-      # Verify the FQDN folder also includes a valid private key (`privkey.pem` for Certbot, `key.pem` for extraction by Traefik)
-      if [[ -e /etc/letsencrypt/live/${LETSENCRYPT_DOMAIN}/privkey.pem ]]
-      then
-        LETSENCRYPT_KEY='privkey'
-      elif [[ -e /etc/letsencrypt/live/${LETSENCRYPT_DOMAIN}/key.pem ]]
-      then
-        LETSENCRYPT_KEY='key'
-      else
-        _log 'warn' "Cannot find key file ('privkey.pem' or 'key.pem') in '/etc/letsencrypt/live/${LETSENCRYPT_DOMAIN}/'"
-        dms_panic__misconfigured 'LETSENCRYPT_KEY' "${SCOPE_SSL_TYPE}"
-        return 1
-      fi
+      # checks folders in /etc/letsencrypt/live to identify which one to implicitly use:
+      local LETSENCRYPT_DOMAIN LETSENCRYPT_KEY
+      LETSENCRYPT_DOMAIN="$(_find_letsencrypt_domain)"
+      LETSENCRYPT_KEY="$(_find_letsencrypt_key "${LETSENCRYPT_DOMAIN}")"
 
       # Update relevant config for Postfix and Dovecot
       _log 'trace' "Adding ${LETSENCRYPT_DOMAIN} SSL certificate to the postfix and dovecot configuration"
@@ -408,6 +380,54 @@ function _setup_ssl
   esac
 }
 
+
+# Identify a valid letsencrypt FQDN folder to use.
+function _find_letsencrypt_domain
+{
+  local LETSENCRYPT_DOMAIN
+
+  if [[ -n ${SSL_DOMAIN} ]] && [[ -e /etc/letsencrypt/live/$(_strip_wildcard_prefix "${SSL_DOMAIN}")/fullchain.pem ]]
+  then
+    LETSENCRYPT_DOMAIN=$(_strip_wildcard_prefix "${SSL_DOMAIN}")
+  elif [[ -e /etc/letsencrypt/live/${HOSTNAME}/fullchain.pem ]]
+  then
+    LETSENCRYPT_DOMAIN=${HOSTNAME}
+  elif [[ -e /etc/letsencrypt/live/${DOMAINNAME}/fullchain.pem ]]
+  then
+    LETSENCRYPT_DOMAIN=${DOMAINNAME}
+  else
+    _log 'error' "Cannot find a valid DOMAIN for '/etc/letsencrypt/live/<DOMAIN>/', tried: '${SSL_DOMAIN}', '${HOSTNAME}', '${DOMAINNAME}'"
+    dms_panic__misconfigured 'LETSENCRYPT_DOMAIN' '_find_letsencrypt_domain'
+  fi
+
+  echo "${LETSENCRYPT_DOMAIN}"
+}
+
+# Verify the FQDN folder also includes a valid private key (`privkey.pem` for Certbot, `key.pem` for extraction by Traefik)
+function _find_letsencrypt_key
+{
+  local LETSENCRYPT_KEY
+
+  local LETSENCRYPT_DOMAIN=${1}
+  if [[ -z ${LETSENCRYPT_DOMAIN} ]]
+  then
+    dms_panic__misconfigured 'LETSENCRYPT_DOMAIN' '_find_letsencrypt_key'
+  fi
+
+  if [[ -e /etc/letsencrypt/live/${LETSENCRYPT_DOMAIN}/privkey.pem ]]
+  then
+    LETSENCRYPT_KEY='privkey'
+  elif [[ -e /etc/letsencrypt/live/${LETSENCRYPT_DOMAIN}/key.pem ]]
+  then
+    LETSENCRYPT_KEY='key'
+  else
+    _log 'error' "Cannot find key file ('privkey.pem' or 'key.pem') in '/etc/letsencrypt/live/${LETSENCRYPT_DOMAIN}/'"
+    dms_panic__misconfigured 'LETSENCRYPT_KEY' '_find_letsencrypt_key'
+  fi
+
+  echo "${LETSENCRYPT_KEY}"
+}
+
 function _extract_certs_from_acme
 {
   local CERT_DOMAIN=${1}