refactor: acme.json extraction (#2274)

Split into scoped commits with messages if further details are needed, view those via the associated PR :)

**Commit Summary:**

**`check-for-changes.sh`**

- Prevent `SSL_DOMAIN` silently skipping when value has wildcard prefix `*.` (_at least this was known as a bugfix when originally committed in linked PR_).
- Improved inlined docs for maintainers.
- Additional logging for debugging.

**`helper-functions.sh:_extract_certs_from_acme`**:

- Fail if the input arg (_`$CERT_DOMAIN`, aka the FQDN_) provided for extraction is empty.
- Use `$CERT_DOMAIN` in place of `$HOSTNAME` and `$1` for a consistent value (_previously could mismatch, eg with `SSL_DOMAIN` defined_).
- The conditional is now only for handling extraction failure (_key or cert value is missing from extraction_).
- Log an actual warning or success (debug) based on outcome.
- Don't use `SSL_DOMAIN` with wildcard value for the `mkdir` letsencrypt directory name (_wildcard prefix `*.` is first stripped instead_).

**`acme_extract`** (_new python utility for `acme.json` handling_):

- Extracted out into a python script that can be treated as a utility in the `$PATH` like other helper scripts. It can now be used and optionally tested directly instead of via `helper-functions.sh`.
-Made compatible with Python 3, as Python 2 is EOL and no longer in newer versions of Debian.

target/scripts/helper-functions.sh

@@ -150,51 +150,43 @@ export -f _sanitize_ipv4_to_subnet_cidr
 
 function _extract_certs_from_acme
 {
-  local KEY
-  # shellcheck disable=SC2002
-  KEY=$(cat /etc/letsencrypt/acme.json | python -c "
-import sys,json
-acme = json.load(sys.stdin)
-for key, value in acme.items():
-    certs = value['Certificates']
-    if certs is not None:
-        for cert in certs:
-            if 'domain' in cert and 'key' in cert:
-                if 'main' in cert['domain'] and cert['domain']['main'] == '${1}' or 'sans' in cert['domain'] and '${1}' in cert['domain']['sans']:
-                    print cert['key']
-                    break
-")
-
-  local CERT
-  # shellcheck disable=SC2002
-  CERT=$(cat /etc/letsencrypt/acme.json | python -c "
-import sys,json
-acme = json.load(sys.stdin)
-for key, value in acme.items():
-    certs = value['Certificates']
-    if certs is not None:
-        for cert in certs:
-            if 'domain' in cert and 'certificate' in cert:
-                if 'main' in cert['domain'] and cert['domain']['main'] == '${1}' or 'sans' in cert['domain'] and '${1}' in cert['domain']['sans']:
-                    print cert['certificate']
-                    break
-")
-
-  if [[ -n "${KEY}${CERT}" ]]
+  local CERT_DOMAIN=${1}
+  if [[ -z ${CERT_DOMAIN} ]]
   then
-    mkdir -p "/etc/letsencrypt/live/${HOSTNAME}/"
-
-    echo "${KEY}" | base64 -d >/etc/letsencrypt/live/"${HOSTNAME}"/key.pem || exit 1
-    echo "${CERT}" | base64 -d >/etc/letsencrypt/live/"${HOSTNAME}"/fullchain.pem || exit 1
-    _notify 'inf' "Cert found in /etc/letsencrypt/acme.json for ${1}"
-
-    return 0
-  else
+    _notify 'err' "_extract_certs_from_acme | CERT_DOMAIN is empty"
     return 1
   fi
+
+  local KEY CERT
+  KEY=$(acme_extract /etc/letsencrypt/acme.json "${CERT_DOMAIN}" --key)
+  CERT=$(acme_extract /etc/letsencrypt/acme.json "${CERT_DOMAIN}" --cert)
+
+  if [[ -z ${KEY} ]] || [[ -z ${CERT} ]]
+  then
+    _notify 'warn' "_extract_certs_from_acme | Unable to find key & cert for '${CERT_DOMAIN}' in '/etc/letsencrypt/acme.json'"
+    return 1
+  fi
+
+  # Currently we advise SSL_DOMAIN for wildcard support using a `*.example.com` value,
+  # The filepath however should be `example.com`, avoiding the wildcard part:
+  if [[ ${SSL_DOMAIN} == "${CERT_DOMAIN}" ]]
+  then
+    CERT_DOMAIN=$(_strip_wildcard_prefix "${SSL_DOMAIN}")
+  fi
+
+  mkdir -p "/etc/letsencrypt/live/${CERT_DOMAIN}/"
+  echo "${KEY}" | base64 -d > "/etc/letsencrypt/live/${CERT_DOMAIN}/key.pem" || exit 1
+  echo "${CERT}" | base64 -d > "/etc/letsencrypt/live/${CERT_DOMAIN}/fullchain.pem" || exit 1
+
+  _notify 'inf' "_extract_certs_from_acme | Certificate successfully extracted for '${CERT_DOMAIN}'"
 }
 export -f _extract_certs_from_acme
 
+# Remove the `*.` prefix if it exists
+function _strip_wildcard_prefix {
+  [[ "${1}" == "*."* ]] && echo "${1:2}"
+}
+
 # ? --------------------------------------------- Notifications
 
 function _notify