Metadata-Version: 2.5
Name: certbot-dns-edgeone
Version: 0.1.0
Summary: Tencent Cloud EdgeOne (TEO) DNS Authenticator plugin for Certbot
Project-URL: Homepage, https://github.com/hurole/certbot-dns-edgeone
Project-URL: Repository, https://github.com/hurole/certbot-dns-edgeone
Project-URL: Issues, https://github.com/hurole/certbot-dns-edgeone/issues
Author: Developer
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Requires-Dist: certbot>=2.0.0
Requires-Dist: tencentcloud-sdk-python-teo>=3.0.0
Description-Content-Type: text/markdown

# certbot-dns-edgeone

[English](README.md) | [中文](README.zh-CN.md)

Tencent Cloud **EdgeOne (TEO)** DNS Authenticator plugin for Certbot (similar to `certbot-dns-aliyun` / `certbot-dns-cloudflare`), allowing automated issuance and renewal of Let's Encrypt SSL/TLS certificates (including wildcard certificates).

This plugin automates the process of completing `dns-01` challenges by creating and subsequently removing `_acme-challenge` TXT records via the Tencent Cloud EdgeOne API.

---

## Features

- **Automated DNS-01 Challenge**: Automatically matches the corresponding EdgeOne Zone, creates verification TXT records, and cleans them up after ACME validation.
- **Wildcard Certificate Support**: Full support for single domains, multi-domains (SAN), and wildcard domains (e.g., `*.example.com`).
- **IDN / Punycode Support**: Built-in support for internationalized domain names (Chinese, Japanese, etc.).
- **Smart Zone Discovery & Caching**: Progressively looks up parent domains to locate the EdgeOne Zone ID, with in-memory caching to minimize API requests.
- **Customizable**: Allows specifying a `zone-id` explicitly and configuring custom DNS propagation wait times.

---

## Installation

### Using uv (Recommended)

In your virtual environment:

```bash
uv pip install certbot-dns-edgeone
```

Or install from source:

```bash
git clone https://github.com/hurole/certbot-dns-edgeone.git
cd certbot-dns-edgeone

# Create and activate virtual environment
uv venv
source .venv/bin/activate

# Install in editable mode
uv pip install -e .
```

### Using pip

```bash
pip install certbot certbot-dns-edgeone
```

Verify that Certbot discovers the plugin:

```bash
certbot plugins
```

You should see `* dns-edgeone` listed in the output:
```text
* dns-edgeone
Description: Obtain certificates using a DNS TXT record (if you are using Tencent Cloud EdgeOne for DNS).
Interfaces: Authenticator, Plugin
Entry point: dns-edgeone = certbot_dns_edgeone.dns_edgeone:Authenticator
```

---

## Credentials

1. Go to [Tencent Cloud CAM Console - API Key Management](https://console.cloud.tencent.com/cam/capi) to generate an API key (`SecretId` and `SecretKey`).
2. Ensure the user or role has the required EdgeOne (TEO) permissions (`QcloudTEOFullAccess` or a custom policy granting `teo:DescribeZones`, `teo:CreateDnsRecord`, `teo:DescribeDnsRecords`, and `teo:DeleteDnsRecords`).
3. Create a credentials INI file (e.g., `~/.secrets/certbot/edgeone.ini`):

```ini
# Tencent Cloud EdgeOne API credentials
dns_edgeone_secret_id = YOUR_TENCENTCLOUD_SECRET_ID
dns_edgeone_secret_key = YOUR_TENCENTCLOUD_SECRET_KEY

# Optional: STS Security Token (if using temporary credentials)
# dns_edgeone_token = your_sts_token

# Optional: Manually specify EdgeOne Zone ID (skips auto-discovery)
# dns_edgeone_zone_id = zone-2noz78a8ev6k
```

4. **Secure the credentials file**:

```bash
chmod 600 ~/.secrets/certbot/edgeone.ini
```

---

## Usage

### Request a Certificate

Run `certbot certonly` with the `dns-edgeone` authenticator:

```bash
certbot certonly \
  -a dns-edgeone \
  --dns-edgeone-credentials ~/.secrets/certbot/edgeone.ini \
  --dns-edgeone-propagation-seconds 30 \
  -d example.com \
  -d "*.example.com"
```

### Automatic Renewal

Certbot renews certificates automatically before they expire (usually within 30 days) via cron or a systemd timer.

Test renewal using dry-run mode:

```bash
certbot renew --dry-run
```

---

## Arguments

| Argument | Default | Description |
| :--- | :--- | :--- |
| `--dns-edgeone-credentials` | Required | Path to INI credentials file containing EdgeOne API `secret_id` and `secret_key` |
| `--dns-edgeone-propagation-seconds` | `30` | Seconds to wait for DNS propagation before ACME validation |
| `--dns-edgeone-zone-id` | Auto | Optional EdgeOne Zone ID (e.g. `zone-xxxxxx`) to override automatic discovery |

---

## Development & Testing

Run the test suite using `pytest`:

```bash
uv pip install pytest
pytest -v
```

---

## License

[Apache License 2.0](LICENSE)
