ESA DNS + ACME Certificate Automation

Design Decision (Important)

This skill combines acme.sh + ESA DNS into a single integrated flow, not split into two skills.

Reasons: 1. The two steps are tightly coupled: ACME challenge tokens must be written to ESA DNS immediately. 2. The most common user errors are "validation failed / record written to the wrong panel" — an integrated flow minimizes mistakes. 3. Wildcard scenarios often produce multiple TXT values for the same FQDN; splitting would increase manual synchronization cost.

If there is significant demand for "DNS-only operations" in the future, a separate esa-dns-records helper skill can be extracted.

---

When to Trigger

Trigger when any of the following apply: - Domain NS records are on *.atrustdns.com (ESA-hosted DNS) - User says "issue certificate with acme.sh", "Let's Encrypt", "DNS-01" - Error: No TXT record found at _acme-challenge... - Need to issue example.com + *.example.com together - Need to auto-write ESA DNS records and install to Nginx

---

Supported Environment

• Linux hosts (recommended: Ubuntu tested)
• System-level Nginx (LNMP tested)
• Docker/containerized environments are not supported
• Not tested on Windows/macOS

Prerequisites

Install acme.sh from the official project before using this skill, and review the installation method you choose instead of piping remote scripts directly to a shell:

• https://github.com/acmesh-official/acme.sh

This skill expects acme.sh to be available on PATH. The script also falls back to ~/.acme.sh/acme.sh if present.

Requirements:

• Credentials via ALIYUN_AK / ALIYUN_SK or ALIBABACLOUD_ACCESS_KEY_ID / ALIBABACLOUD_ACCESS_KEY_SECRET
• STS token is supported via ALIYUN_SECURITY_TOKEN, ALIBABACLOUD_SECURITY_TOKEN, or --sts-token
• If the user provides credentials directly in OpenClaw chat/TUI as plain id / secret / token values without env names, treat them as generic Alibaba Cloud AccessKeyId / AccessKeySecret / SecurityToken and pass them to --ak / --sk / --sts-token. Do not block on whether the user said Aliyun or Alibaba Cloud; let the script auto-detect the ESA region/site.

---

Running the Script

Script path: scripts/esa_acme_issue.py

Default behavior (optimized):

• Certificate installation to Nginx is disabled by default; opt in with --install-cert
• --dns-timeout defaults to 600 seconds
• Optional IPv4/IPv6 record management: --ensure-a-record host=ip (with authoritative NS propagation check)
• Overwrite protection: existing A value is NOT overwritten unless --confirm-overwrite is passed
• --lang selects output language (default: en; available languages auto-discovered from scripts/i18n/)
• If --install-cert is used, run on a controlled Linux host with permission to write the target cert paths and reload Nginx

Single domain

export ALIYUN_AK='YOUR_AK'
export ALIYUN_SK='YOUR_SK'
export ALIYUN_SECURITY_TOKEN='YOUR_STS_TOKEN'   # optional but recommended
python3 scripts/esa_acme_issue.py 
  -d test.example.com

Equivalent Alibaba Cloud env names are also accepted:

export ALIBABACLOUD_ACCESS_KEY_ID='YOUR_AK'
export ALIBABACLOUD_ACCESS_KEY_SECRET='YOUR_SK'
export ALIBABACLOUD_SECURITY_TOKEN='YOUR_STS_TOKEN'   # optional

Apex + wildcard (recommended order)

export ALIYUN_AK='YOUR_AK'
export ALIYUN_SK='YOUR_SK'
python3 scripts/esa_acme_issue.py 
  -d example.com 
  -d '*.example.com'

Wildcard only

python3 scripts/esa_acme_issue.py 
  -d '*.example.com'

---

Correct Nginx Configuration

ssl_certificate     /etc/nginx/ssl/example.com.crt;
ssl_certificate_key /etc/nginx/ssl/example.com.key;

---

Completion Criteria (Anti False-Positive)

Before reporting "record created / DNS ready", both conditions must be met:

1) ListRecords returns the target RecordName + Type + Value; 2) Authoritative NS dig @ns TXT returns the expected token.

If only the CreateRecord API returned success (RequestId/RecordId only) without passing both checks above, report "request accepted", not "completed".

Troubleshooting Quick Reference

1. InvalidRecordNameSuffix

2. Domain suffix does not belong to the current ESA site (common typo).

3. No TXT record found at _acme-challenge...

4. TXT not yet propagated to all authoritative NS; increase --dns-timeout to 300–600.

5. Permission / signature errors after setting AccessKey IP whitelist

6. Check current public egress IP: curl -s ifconfig.me
7. Whitelist the actual egress NAT IP (not LAN IP)
8. If behind proxy/gateway, whitelist the proxy egress IP
9. Wait briefly after whitelist update before retrying

---

Security Guidelines

Before each execution, remind the user: 1) Use a RAM sub-account with minimal permissions. Do NOT use the primary account long-term AK. 2) Prefer STS temporary credentials to reduce leak risk. 3) Enable AccessKey IP whitelist, allowing only the actual egress NAT IP.