certbot-dns-edgeone 0.1.0__tar.gz

certbot_dns_edgeone-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      # Required for PyPI Trusted Publishing
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # If using API token instead of trusted publishing:
+          # password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true

certbot_dns_edgeone-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.coverage
+htmlcov/
+.DS_Store
+credentials.ini

certbot_dns_edgeone-0.1.0/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

certbot_dns_edgeone-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+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)

certbot_dns_edgeone-0.1.0/README.md

@@ -0,0 +1,143 @@
+# 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)

certbot_dns_edgeone-0.1.0/README.zh-CN.md

@@ -0,0 +1,146 @@
+# certbot-dns-edgeone
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+适用于腾讯云 **EdgeOne (TEO)** 的 Certbot DNS 认证插件（类似于 `certbot-dns-aliyun` / `certbot-dns-cloudflare`），用于自动化申请与续期 Let's Encrypt 等 ACME SSL/TLS 证书（支持泛域名证书）。
+
+通过调用腾讯云 EdgeOne API 自动添加和清理 `_acme-challenge` TXT 解析记录，完成 DNS-01 质询。
+
+---
+
+## 特性
+
+- **全自动 DNS-01 验证**：自动匹配站点 (Zone)、创建 TXT 记录、DNS 校验完成后自动清理记录。
+- **支持泛域名**：支持申请单域名、多域名以及泛域名（通配符 `*.example.com`）证书。
+- **国际化域名 (IDN / Punycode)**：原生支持中文、日文等 Punycode 域名转换。
+- **智能站点匹配与缓存**：自动向上递归查找对应的 EdgeOne 站点 ID，并在证书申请过程中进行缓存，减少 API 调用。
+- **自定义站点与传播延迟**：支持通过参数手动指定 `zone-id`，支持自定义 DNS 传播等待时间。
+
+---
+
+## 安装方法
+
+### 通过 uv 安装（推荐）
+
+在虚拟环境中使用 `uv`：
+
+```bash
+uv pip install certbot-dns-edgeone
+```
+
+如果使用本项目本地源码安装：
+
+```bash
+git clone https://github.com/hurole/certbot-dns-edgeone.git
+cd certbot-dns-edgeone
+
+# 创建并激活虚拟环境
+uv venv
+source .venv/bin/activate
+
+# 安装开发与运行依赖
+uv pip install -e .
+```
+
+### 通过 pip 安装
+
+```bash
+pip install certbot certbot-dns-edgeone
+```
+
+验证插件是否已被 Certbot 正确识别：
+
+```bash
+certbot plugins
+```
+
+若输出中包含 `dns-edgeone` 即表示安装成功：
+```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
+```
+
+---
+
+## 凭据准备
+
+1. 前往 [腾讯云访问管理 (CAM) 控制台 - API 密钥管理](https://console.cloud.tencent.com/cam/capi) 创建或获取 API 密钥（`SecretId` 和 `SecretKey`）。
+2. 请确保该子用户或密钥拥有 EdgeOne (TEO) 相关的权限策略（如 `QcloudTEOFullAccess`，或包含 `teo:DescribeZones`、`teo:CreateDnsRecord`、`teo:DescribeDnsRecords`、`teo:DeleteDnsRecords` 的自定义策略）。
+3. 创建凭据配置文件（例如 `~/.secrets/certbot/edgeone.ini`）：
+
+```ini
+# 腾讯云 EdgeOne API 凭据
+dns_edgeone_secret_id = YOUR_TENCENTCLOUD_SECRET_ID
+dns_edgeone_secret_key = YOUR_TENCENTCLOUD_SECRET_KEY
+
+# 可选：如果使用 STS 临时密钥，填写 security token
+# dns_edgeone_token = your_sts_token
+
+# 可选：手动指定 EdgeOne 站点 ID（若指定则跳过站点自动搜索）
+# dns_edgeone_zone_id = zone-2noz78a8ev6k
+```
+
+4. **重要安全保护**：为避免凭据泄露，请将该文件的权限限制为仅当前用户可读写：
+
+```bash
+chmod 600 ~/.secrets/certbot/edgeone.ini
+```
+
+---
+
+## 使用方法
+
+### 申请证书
+
+使用 `certbot certonly` 命令配合 `dns-edgeone` 认证器：
+
+```bash
+certbot certonly \
+  -a dns-edgeone \
+  --dns-edgeone-credentials ~/.secrets/certbot/edgeone.ini \
+  --dns-edgeone-propagation-seconds 30 \
+  -d example.com \
+  -d "*.example.com"
+```
+
+### 自动续期
+
+Certbot 会在证书过期前（通常剩余 30 天内）通过定时任务（如 cron 或 systemd timer）执行 `certbot renew`。
+
+由于认证参数和凭据路径已保存在续期配置中，只需测试续期命令：
+
+```bash
+certbot renew --dry-run
+```
+
+---
+
+## 参数说明
+
+| 参数 | 默认值 | 描述 |
+| :--- | :--- | :--- |
+| `--dns-edgeone-credentials` | 必填 | 包含 EdgeOne API `secret_id` 和 `secret_key` 的 INI 配置文件路径 |
+| `--dns-edgeone-propagation-seconds` | `30` | 创建 DNS 记录后等待 DNS 解析生效的等待秒数 |
+| `--dns-edgeone-zone-id` | 自动匹配 | 可选，手动指定 EdgeOne 站点 ID（形如 `zone-xxxxxx`） |
+
+---
+
+## 开发与测试
+
+在虚拟环境中运行测试：
+
+```bash
+# 安装测试工具
+uv pip install pytest
+
+# 执行单元测试
+pytest -v
+```
+
+---
+
+## License
+
+[Apache License 2.0](LICENSE)

certbot_dns_edgeone-0.1.0/certbot_dns_edgeone/__init__.py

@@ -0,0 +1,3 @@
+"""Certbot DNS Authenticator plugin for Tencent Cloud EdgeOne (TEO)."""
+
+__version__ = "0.1.0"

certbot_dns_edgeone-0.1.0/certbot_dns_edgeone/client.py

@@ -0,0 +1,233 @@
+"""EdgeOne (TEO) DNS API client wrapper."""
+
+import logging
+from typing import Dict, List, Optional, Tuple
+
+from certbot import errors
+from certbot.plugins import dns_common
+from tencentcloud.common import credential
+from tencentcloud.common.exception.tencent_cloud_sdk_exception import (
+    TencentCloudSDKException,
+)
+from tencentcloud.common.profile.client_profile import ClientProfile
+from tencentcloud.common.profile.http_profile import HttpProfile
+from tencentcloud.teo.v20220901 import models, teo_client
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TTL = 60
+DEFAULT_ENDPOINT = "teo.tencentcloudapi.com"
+
+
+class EdgeOneDNSClient:
+    """Encapsulates all communication with Tencent Cloud EdgeOne (TEO) API."""
+
+    def __init__(
+        self,
+        secret_id: str,
+        secret_key: str,
+        token: Optional[str] = None,
+        zone_id: Optional[str] = None,
+        ttl: int = DEFAULT_TTL,
+        endpoint: str = DEFAULT_ENDPOINT,
+    ):
+        self.secret_id = secret_id
+        self.secret_key = secret_key
+        self.token = token
+        self.zone_id = zone_id
+        self.ttl = max(60, ttl)  # EdgeOne minimum TTL is 60 seconds
+        self.endpoint = endpoint
+
+        self._client: Optional[teo_client.TeoClient] = None
+        self._zone_cache: Dict[str, str] = {}
+        self._created_records: Dict[Tuple[str, str], Tuple[str, str]] = {}
+
+    @property
+    def client(self) -> teo_client.TeoClient:
+        if self._client is None:
+            cred = credential.Credential(self.secret_id, self.secret_key, self.token)
+            http_profile = HttpProfile()
+            http_profile.endpoint = self.endpoint
+            client_profile = ClientProfile(httpProfile=http_profile)
+            self._client = teo_client.TeoClient(cred, "", client_profile)
+        return self._client
+
+    def _to_punycode(self, name: str) -> str:
+        """Convert internationalized domain names (IDN) to punycode format."""
+        try:
+            return name.encode("idna").decode("ascii")
+        except Exception:
+            return name
+
+    def _find_zone_id(self, domain: str) -> str:
+        """Find the ZoneId corresponding to the given domain."""
+        if self.zone_id:
+            return self.zone_id
+
+        norm_domain = domain.lstrip("*.").rstrip(".")
+        ascii_domain = self._to_punycode(norm_domain)
+
+        if ascii_domain in self._zone_cache:
+            return self._zone_cache[ascii_domain]
+
+        guesses = [
+            g
+            for g in dns_common.base_domain_name_guesses(ascii_domain)
+            if g and not g.startswith("*")
+        ]
+
+        for guess in guesses:
+            try:
+                req = models.DescribeZonesRequest()
+                f = models.AdvancedFilter()
+                f.Name = "zone-name"
+                f.Values = [guess]
+                f.Fuzzy = False
+                req.Filters = [f]
+                req.Limit = 20
+
+                resp = self.client.DescribeZones(req)
+                if resp.Zones:
+                    for zone in resp.Zones:
+                        if zone.ZoneName == guess:
+                            self._zone_cache[ascii_domain] = zone.ZoneId
+                            return zone.ZoneId
+            except TencentCloudSDKException as e:
+                raise self._handle_sdk_error(
+                    e, f"Error searching zone for {guess} (domain: {domain})"
+                )
+
+        raise errors.PluginError(
+            f"Unable to determine EdgeOne zone identifier for {domain} using candidates: {guesses}"
+        )
+
+    def add_txt_record(self, domain: str, record_name: str, value: str) -> str:
+        """Create a DNS TXT record for domain validation.
+
+        :param str domain: The target domain.
+        :param str record_name: The validation record name (FQDN).
+        :param str value: The validation value (TXT content).
+        :return: The created record ID.
+        """
+        zone_id = self._find_zone_id(domain)
+        name = self._to_punycode(record_name.rstrip("."))
+
+        req = models.CreateDnsRecordRequest()
+        req.ZoneId = zone_id
+        req.Type = "TXT"
+        req.Name = name
+        req.Content = value
+        req.TTL = self.ttl
+
+        try:
+            resp = self.client.CreateDnsRecord(req)
+            record_id = resp.RecordId
+            self._created_records[(name, value)] = (zone_id, record_id)
+            logger.debug(
+                "Created EdgeOne TXT record '%s' with ID %s in zone %s",
+                name,
+                record_id,
+                zone_id,
+            )
+            return record_id
+        except TencentCloudSDKException as e:
+            raise self._handle_sdk_error(
+                e, f"Error creating TXT record '{name}' for domain '{domain}'"
+            )
+
+    def del_txt_record(self, domain: str, record_name: str, value: str) -> None:
+        """Delete a DNS TXT record.
+
+        :param str domain: The target domain.
+        :param str record_name: The validation record name (FQDN).
+        :param str value: The validation value (TXT content).
+        """
+        name = self._to_punycode(record_name.rstrip("."))
+
+        # 1. Check if record was created in this session
+        cached = self._created_records.pop((name, value), None)
+        if cached:
+            zone_id, record_id = cached
+            self._delete_records_by_id(zone_id, [record_id], name)
+            return
+
+        # 2. If not cached, lookup by querying DescribeDnsRecords
+        try:
+            zone_id = self._find_zone_id(domain)
+        except errors.PluginError as e:
+            logger.warning("Could not determine zone ID during cleanup of %s: %s", name, e)
+            return
+
+        try:
+            req = models.DescribeDnsRecordsRequest()
+            req.ZoneId = zone_id
+            f_name = models.AdvancedFilter()
+            f_name.Name = "name"
+            f_name.Values = [name]
+            f_name.Fuzzy = False
+
+            f_type = models.AdvancedFilter()
+            f_type.Name = "type"
+            f_type.Values = ["TXT"]
+            f_type.Fuzzy = False
+
+            req.Filters = [f_name, f_type]
+            req.Limit = 100
+
+            resp = self.client.DescribeDnsRecords(req)
+            record_ids_to_del: List[str] = []
+            if resp.DnsRecords:
+                for rec in resp.DnsRecords:
+                    # Strip quotation marks if present
+                    if rec.Content and rec.Content.strip('"') == value.strip('"'):
+                        record_ids_to_del.append(rec.RecordId)
+
+            if record_ids_to_del:
+                self._delete_records_by_id(zone_id, record_ids_to_del, name)
+            else:
+                logger.debug("No matching EdgeOne TXT record found for %s to delete", name)
+        except TencentCloudSDKException as e:
+            logger.warning("Error searching for TXT record %s to delete: %s", name, e)
+
+    def _delete_records_by_id(
+        self, zone_id: str, record_ids: List[str], record_name: str
+    ) -> None:
+        """Helper to invoke DeleteDnsRecords."""
+        req = models.DeleteDnsRecordsRequest()
+        req.ZoneId = zone_id
+        req.RecordIds = record_ids
+        try:
+            self.client.DeleteDnsRecords(req)
+            logger.debug(
+                "Deleted EdgeOne TXT record(s) %s for %s in zone %s",
+                record_ids,
+                record_name,
+                zone_id,
+            )
+        except TencentCloudSDKException as e:
+            logger.warning(
+                "Failed to delete EdgeOne TXT record(s) %s for %s: %s",
+                record_ids,
+                record_name,
+                e,
+            )
+
+    def _handle_sdk_error(
+        self, e: TencentCloudSDKException, context: str
+    ) -> errors.PluginError:
+        """Format TencentCloud SDK error messages with troubleshooting hints."""
+        msg = f"{context}: [{e.code}] {e.message} (RequestId: {e.requestId})"
+        code_str = str(e.code)
+        if any(k in code_str for k in ("AuthFailure", "SecretId", "Signature")):
+            msg += (
+                "\nTroubleshooting: Please ensure your secret_id and secret_key are valid "
+                "and have the required EdgeOne permissions in Tencent Cloud CAM."
+            )
+        elif "ResourceNotFound" in code_str:
+            msg += "\nTroubleshooting: The specified EdgeOne zone or record was not found."
+        elif "UnauthorizedOperation" in code_str:
+            msg += (
+                "\nTroubleshooting: Your Tencent Cloud CAM user/role does not have permission "
+                "to perform this action on EdgeOne."
+            )
+        return errors.PluginError(msg)

certbot_dns_edgeone-0.1.0/certbot_dns_edgeone/dns_edgeone.py

@@ -0,0 +1,73 @@
+"""DNS Authenticator for Tencent Cloud EdgeOne (TEO)."""
+
+import logging
+from typing import Optional
+
+from certbot.plugins import dns_common
+from certbot_dns_edgeone.client import DEFAULT_TTL, EdgeOneDNSClient
+
+logger = logging.getLogger(__name__)
+
+
+class Authenticator(dns_common.DNSAuthenticator):
+    """DNS Authenticator for Tencent Cloud EdgeOne (TEO)
+
+    This Authenticator uses the Tencent Cloud EdgeOne API to fulfill a dns-01 challenge.
+    """
+
+    description = (
+        "Obtain certificates using a DNS TXT record (if you are using Tencent Cloud EdgeOne for DNS)."
+    )
+    ttl = DEFAULT_TTL
+    _client: Optional[EdgeOneDNSClient] = None
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.credentials = None
+
+    @classmethod
+    def add_parser_arguments(cls, add, default_propagation_seconds=30):
+        super().add_parser_arguments(
+            add, default_propagation_seconds=default_propagation_seconds
+        )
+        add("credentials", help="Tencent Cloud EdgeOne credentials INI file.")
+        add("zone-id", help="Optional EdgeOne Zone ID (e.g. zone-xxxxxxxx) to override auto-discovery.")
+
+    def more_info(self) -> str:
+        return (
+            "This plugin configures a DNS TXT record to respond to a dns-01 challenge using "
+            "the Tencent Cloud EdgeOne (TEO) API."
+        )
+
+    def _setup_credentials(self) -> None:
+        self.credentials = self._configure_credentials(
+            "credentials",
+            "Tencent Cloud EdgeOne credentials INI file",
+            {
+                "secret-id": "SecretId for Tencent Cloud API, obtained from CAM console",
+                "secret-key": "SecretKey for Tencent Cloud API, obtained from CAM console",
+            },
+        )
+
+    def _get_client(self) -> EdgeOneDNSClient:
+        if not self._client:
+            secret_id = self.credentials.conf("secret-id")
+            secret_key = self.credentials.conf("secret-key")
+            token = self.credentials.conf("token")
+
+            zone_id = self.conf("zone-id") or self.credentials.conf("zone-id")
+
+            self._client = EdgeOneDNSClient(
+                secret_id=secret_id,
+                secret_key=secret_key,
+                token=token,
+                zone_id=zone_id,
+                ttl=self.ttl,
+            )
+        return self._client
+
+    def _perform(self, domain: str, validation_name: str, validation: str) -> None:
+        self._get_client().add_txt_record(domain, validation_name, validation)
+
+    def _cleanup(self, domain: str, validation_name: str, validation: str) -> None:
+        self._get_client().del_txt_record(domain, validation_name, validation)

certbot_dns_edgeone-0.1.0/credentials.example.ini

@@ -0,0 +1,12 @@
+# 腾讯云 EdgeOne (TEO) API 凭据文件
+# 获取方式：登录腾讯云控制台 -> 访问管理 (CAM) -> API 密钥管理
+# 注意：该文件包含敏感凭据，请确保权限为 600 (chmod 600 /path/to/credentials.ini)
+
+dns_edgeone_secret_id = YOUR_TENCENTCLOUD_SECRET_ID
+dns_edgeone_secret_key = YOUR_TENCENTCLOUD_SECRET_KEY
+
+# 可选配置（若使用 STS 临时密钥，需配置 token）：
+# dns_edgeone_token = your_security_token
+
+# 可选配置（指定特定的 EdgeOne 站点 ID，跳过自动查找站点）：
+# dns_edgeone_zone_id = zone-2noz78a8ev6k

certbot_dns_edgeone-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "certbot-dns-edgeone"
+version = "0.1.0"
+description = "Tencent Cloud EdgeOne (TEO) DNS Authenticator plugin for Certbot"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Developer" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Plugins",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: Name Service (DNS)",
+    "Topic :: Security",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "certbot>=2.0.0",
+    "tencentcloud-sdk-python-teo>=3.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/hurole/certbot-dns-edgeone"
+Repository = "https://github.com/hurole/certbot-dns-edgeone"
+Issues = "https://github.com/hurole/certbot-dns-edgeone/issues"
+
+[project.entry-points."certbot.plugins"]
+dns-edgeone = "certbot_dns_edgeone.dns_edgeone:Authenticator"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-mock>=3.10.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["certbot_dns_edgeone"]

certbot_dns_edgeone-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for certbot-dns-edgeone."""

certbot_dns_edgeone-0.1.0/tests/test_dns_edgeone.py

@@ -0,0 +1,176 @@
+"""Unit tests for certbot_dns_edgeone."""
+
+import os
+import tempfile
+import unittest
+from unittest.mock import MagicMock, patch
+
+from certbot import errors
+from certbot.plugins import dns_test_common
+from tencentcloud.common.exception.tencent_cloud_sdk_exception import (
+    TencentCloudSDKException,
+)
+from tencentcloud.teo.v20220901 import models
+
+from certbot_dns_edgeone.client import EdgeOneDNSClient
+from certbot_dns_edgeone.dns_edgeone import Authenticator
+
+API_SECRET_ID = "test-secret-id"
+API_SECRET_KEY = "test-secret-key"
+ZONE_ID = "zone-12345678"
+DOMAIN = "example.com"
+VALIDATION_NAME = "_acme-challenge.example.com"
+VALIDATION_VALUE = "validationsampletoken123"
+
+
+class EdgeOneDNSClientTest(unittest.TestCase):
+    def setUp(self):
+        self.client = EdgeOneDNSClient(
+            secret_id=API_SECRET_ID,
+            secret_key=API_SECRET_KEY,
+            ttl=60,
+        )
+        self.mock_teo_client = MagicMock()
+        self.client._client = self.mock_teo_client
+
+    def test_find_zone_id_explicit(self):
+        self.client.zone_id = "zone-explicit"
+        self.assertEqual(self.client._find_zone_id("test.example.com"), "zone-explicit")
+        self.mock_teo_client.DescribeZones.assert_not_called()
+
+    def test_find_zone_id_auto(self):
+        resp = models.DescribeZonesResponse()
+        zone = models.Zone()
+        zone.ZoneId = ZONE_ID
+        zone.ZoneName = "example.com"
+        resp.Zones = [zone]
+        resp.TotalCount = 1
+        self.mock_teo_client.DescribeZones.return_value = resp
+
+        zone_id = self.client._find_zone_id("sub.example.com")
+        self.assertEqual(zone_id, ZONE_ID)
+        # Verify caching
+        self.assertEqual(self.client._zone_cache.get("sub.example.com"), ZONE_ID)
+        # Calling again should use cache without invoking API
+        self.mock_teo_client.DescribeZones.reset_mock()
+        self.assertEqual(self.client._find_zone_id("sub.example.com"), ZONE_ID)
+        self.mock_teo_client.DescribeZones.assert_not_called()
+
+    def test_find_zone_id_not_found(self):
+        resp = models.DescribeZonesResponse()
+        resp.Zones = []
+        resp.TotalCount = 0
+        self.mock_teo_client.DescribeZones.return_value = resp
+
+        with self.assertRaises(errors.PluginError):
+            self.client._find_zone_id("notfound.org")
+
+    def test_find_zone_id_sdk_error(self):
+        self.mock_teo_client.DescribeZones.side_effect = TencentCloudSDKException(
+            code="AuthFailure", message="SecretId is invalid", requestId="req-1"
+        )
+        with self.assertRaises(errors.PluginError) as ctx:
+            self.client._find_zone_id("example.com")
+        self.assertIn("AuthFailure", str(ctx.exception))
+
+    def test_add_txt_record(self):
+        # mock zone discovery
+        self.client._zone_cache["example.com"] = ZONE_ID
+
+        resp = models.CreateDnsRecordResponse()
+        resp.RecordId = "record-987"
+        self.mock_teo_client.CreateDnsRecord.return_value = resp
+
+        rec_id = self.client.add_txt_record(DOMAIN, VALIDATION_NAME, VALIDATION_VALUE)
+        self.assertEqual(rec_id, "record-987")
+
+        self.mock_teo_client.CreateDnsRecord.assert_called_once()
+        req = self.mock_teo_client.CreateDnsRecord.call_args[0][0]
+        self.assertEqual(req.ZoneId, ZONE_ID)
+        self.assertEqual(req.Name, VALIDATION_NAME)
+        self.assertEqual(req.Type, "TXT")
+        self.assertEqual(req.Content, VALIDATION_VALUE)
+        self.assertEqual(req.TTL, 60)
+
+    def test_del_txt_record_cached(self):
+        self.client._created_records[(VALIDATION_NAME, VALIDATION_VALUE)] = (
+            ZONE_ID,
+            "record-987",
+        )
+
+        resp = models.DeleteDnsRecordsResponse()
+        resp.RequestId = "req-del-1"
+        self.mock_teo_client.DeleteDnsRecords.return_value = resp
+
+        self.client.del_txt_record(DOMAIN, VALIDATION_NAME, VALIDATION_VALUE)
+
+        self.mock_teo_client.DeleteDnsRecords.assert_called_once()
+        req = self.mock_teo_client.DeleteDnsRecords.call_args[0][0]
+        self.assertEqual(req.ZoneId, ZONE_ID)
+        self.assertEqual(req.RecordIds, ["record-987"])
+
+    def test_del_txt_record_uncached_query(self):
+        self.client._zone_cache["example.com"] = ZONE_ID
+
+        # Mock DescribeDnsRecords
+        resp_desc = models.DescribeDnsRecordsResponse()
+        r1 = models.DnsRecord()
+        r1.RecordId = "record-query-1"
+        r1.Content = f'"{VALIDATION_VALUE}"'  # Quotes in content
+        resp_desc.DnsRecords = [r1]
+        self.mock_teo_client.DescribeDnsRecords.return_value = resp_desc
+
+        resp_del = models.DeleteDnsRecordsResponse()
+        self.mock_teo_client.DeleteDnsRecords.return_value = resp_del
+
+        self.client.del_txt_record(DOMAIN, VALIDATION_NAME, VALIDATION_VALUE)
+
+        self.mock_teo_client.DescribeDnsRecords.assert_called_once()
+        self.mock_teo_client.DeleteDnsRecords.assert_called_once()
+        req = self.mock_teo_client.DeleteDnsRecords.call_args[0][0]
+        self.assertEqual(req.ZoneId, ZONE_ID)
+        self.assertEqual(req.RecordIds, ["record-query-1"])
+
+
+class AuthenticatorPluginTest(unittest.TestCase):
+    def setUp(self):
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.config_path = os.path.join(self.temp_dir.name, "credentials.ini")
+        dns_test_common.write(
+            {
+                "edgeone_secret_id": API_SECRET_ID,
+                "edgeone_secret_key": API_SECRET_KEY,
+            },
+            self.config_path,
+        )
+
+        self.config = MagicMock()
+        self.config.edgeone_credentials = self.config_path
+        self.config.edgeone_zone_id = None
+        self.config.edgeone_propagation_seconds = 0
+
+        self.auth = Authenticator(self.config, "edgeone")
+        self.mock_client = MagicMock()
+        self.auth._get_client = MagicMock(return_value=self.mock_client)
+
+    def tearDown(self):
+        self.temp_dir.cleanup()
+
+    def test_more_info(self):
+        self.assertIsInstance(self.auth.more_info(), str)
+
+    def test_perform(self):
+        self.auth._perform(DOMAIN, VALIDATION_NAME, VALIDATION_VALUE)
+        self.mock_client.add_txt_record.assert_called_once_with(
+            DOMAIN, VALIDATION_NAME, VALIDATION_VALUE
+        )
+
+    def test_cleanup(self):
+        self.auth._cleanup(DOMAIN, VALIDATION_NAME, VALIDATION_VALUE)
+        self.mock_client.del_txt_record.assert_called_once_with(
+            DOMAIN, VALIDATION_NAME, VALIDATION_VALUE
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()