docs: update CLAUDE.md, README, readme.ru.md for acme.sh and DNS-01 support

Author: jorikfon

CLAUDE.md

@@ -4,7 +4,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Overview
 
-MikoPBX extension module for automated SSL certificate management via Let's Encrypt (ACME v2). Uses the `getssl` bash script as the ACME client with HTTP-01 validation, and provides real-time certificate request progress via nchan Pub/Sub or polling fallback.
+MikoPBX extension module for automated SSL certificate management via Let's Encrypt (ACME v2). Uses `acme.sh` as the primary ACME client with support for both **HTTP-01** and **DNS-01** validation methods. Provides real-time certificate request progress via nchan Pub/Sub or polling fallback.
+
+**DNS-01 support** enables certificate issuance without opening port 80, using DNS provider APIs (Cloudflare, AWS Route53, Hetzner, Yandex Cloud, and 150+ others). Also supports wildcard certificates (`*.domain.com`).
+
+Legacy `getssl` client files are retained for one transition release cycle.
 
 ## Build Commands
 
@@ -23,59 +27,84 @@ Repeat for each source file (`module-get-ssl-index.js`, `module-get-ssl-status-w
 ```bash
 phpstan analyse
 ```
-Config in `phpstan.neon`: level 0, scans `Lib/`, `Models/`, `bin/`, `App/`, `Setup/`. Requires MikoPBX Core sources at `../../Core/src` for class resolution. Ignores Phalcon 4/5 compatibility class-not-found errors.
+Config in `phpstan.neon`: level 0, scans `Lib/`, `Models/`, `bin/`, `App/`, `Setup/`. Requires MikoPBX Core sources at `../../Core/src` for class resolution. Ignores Phalcon 4/5 compatibility class-not-found errors. The `bin/` scripts report `Globals.php` not found — this is expected (runtime file from MikoPBX DI container).
 
 ## Architecture
 
 ### PSR-4 Namespace
 Root namespace `Modules\ModuleGetSsl\` maps to repository root (see `composer.json`).
 
 ### Module Lifecycle
-1. **Installation** (`Setup/PbxExtensionSetup.php`): Creates DB table `m_ModuleGetSsl`, sets defaults, detects domain from internet interface
+1. **Installation** (`Setup/PbxExtensionSetup.php`): Creates DB table `m_ModuleGetSsl`, sets defaults (including `challengeType='http'` for migration), detects domain from internet interface
 2. **Runtime** (`Lib/GetSslConf.php`): Registers REST API callbacks, cron tasks, reacts to model changes and PBX lifecycle events
-3. **Certificate Request** (`Lib/GetSslMain.php`): Generates getssl config, launches async certificate request, streams progress to browser
-4. **Port 80 Management** (`Lib/AcmeHttpPort.php`): Temporarily opens port 80 for ACME HTTP-01 validation — creates nginx server block at `/etc/nginx/mikopbx/modules_servers/ModuleGetSsl_acme80.conf`, adds iptables rules when firewall is active, uses a lock file at `/var/run/custom_modules/ModuleGetSsl/acme_port80.lock` with 300s max open time and automatic stale cleanup
-5. **Uninstall**: Removes symlinks from `/usr/bin/getssl`, `/usr/share/getssl`, `/usr/www/sites/.well-known`
+3. **Certificate Request** (`Lib/GetSslMain.php`): Prepares acme.sh environment, launches async certificate request (HTTP-01 via `--webroot` or DNS-01 via `--dns`), streams progress to browser
+4. **Port 80 Management** (`Lib/AcmeHttpPort.php`): Temporarily opens port 80 for ACME HTTP-01 validation only — creates nginx server block at `/etc/nginx/mikopbx/modules_servers/ModuleGetSsl_acme80.conf`, adds iptables rules when firewall is active, uses a lock file at `/var/run/custom_modules/ModuleGetSsl/acme_port80.lock` with 300s max open time and automatic stale cleanup. **Skipped entirely for DNS-01.**
+5. **Uninstall**: Removes symlinks `/usr/bin/acme.sh`, `/usr/bin/getssl`, `/usr/share/getssl`, `/usr/www/sites/.well-known`
 
 ### Key Classes
 
-- **`Lib/GetSslConf.php`** — Module configuration hook (extends `ConfigClass`). Handles REST API routing (`GET-CERT`, `CHECK-RESULT`), cron task registration, and PBX lifecycle events (`onAfterPbxStarted`, `onAfterModuleEnable`). Wraps cert requests in `AcmeHttpPort::openPort()`/`closePort()` via try/finally
-- **`Lib/GetSslMain.php`** — Core orchestrator. Manages directories, generates getssl config file, launches certificate requests, monitors process completion (120s timeout), pushes real-time updates via nchan, updates SSL keys in PbxSettings DB
-- **`Lib/AcmeHttpPort.php`** — Port 80 lifecycle manager. Opens/closes nginx + iptables for ACME validation. Includes stale lock cleanup (cron watchdog + PBX startup)
+- **`Lib/GetSslMain.php`** — Core orchestrator. Manages directories, prepares acme.sh environment (`prepareAcmeEnvironment()`), builds acme.sh commands for HTTP-01 or DNS-01, launches certificate requests, monitors process completion (120s for HTTP-01 / 300s for DNS-01), pushes real-time updates via nchan, updates SSL keys in PbxSettings DB. Finds certificates in acme.sh paths first, falls back to legacy getssl paths
+- **`Lib/GetSslConf.php`** — Module configuration hook (extends `ConfigClass`). Handles REST API routing (`GET-CERT`, `CHECK-RESULT`), cron task registration, and PBX lifecycle events (`onAfterPbxStarted`, `onAfterModuleEnable`). Conditionally wraps cert requests in `AcmeHttpPort::openPort()`/`closePort()` only for HTTP-01
+- **`Lib/AcmeHttpPort.php`** — Port 80 lifecycle manager. Opens/closes nginx + iptables for ACME HTTP-01 validation. Includes stale lock cleanup (cron watchdog + PBX startup)
+- **`Lib/DnsProviderRegistry.php`** — Static registry of 23 popular DNS providers with env variable definitions. Single source of truth for backend (form select options) and frontend (dynamic credential fields). Methods: `getProviders()`, `getProviderById()`, `getProviderSelectOptions()`
 - **`Lib/MikoPBXVersion.php`** — Compatibility layer for Phalcon 4 vs 5 class names. Version cutoff at PBX 2024.2.30
-- **`Models/ModuleGetSsl.php`** — Phalcon ORM model for `m_ModuleGetSsl` table (fields: `id`, `domainName`, `autoUpdate`). Source table: `m_ModuleGetSsl`
-- **`App/Controllers/ModuleGetSslController.php`** — Web UI controller: renders form, handles save, triggers certificate request on save
-- **`App/Forms/ModuleGetSslForm.php`** — Phalcon form definition. Note: `addCheckBox()` helper exists for backward compat and can be removed when `min_pbx_version` ≥ 2024.3.0
+- **`Models/ModuleGetSsl.php`** — Phalcon ORM model for `m_ModuleGetSsl` table. Fields: `id`, `domainName`, `autoUpdate`, `challengeType` ('http'|'dns'), `dnsProvider` (e.g. 'dns_cf'), `dnsCredentials` (base64-encoded JSON)
+- **`App/Controllers/ModuleGetSslController.php`** — Web UI controller: renders form with DNS provider options, passes `dnsProvidersJson` to view for JS, handles save including `dnsCredentials`
+- **`App/Forms/ModuleGetSslForm.php`** — Phalcon form definition with Select for `challengeType`, Select for `dnsProvider` (with search), Hidden for `dnsCredentials`. Note: `addCheckBox()` helper exists for backward compat and can be removed when `min_pbx_version` ≥ 2024.3.0
+
+### ACME Client (`bin/acme/`)
+
+- **`bin/acme/acme.sh`** — acme.sh ACME client (primary)
+- **`bin/acme/dnsapi/`** — 168 DNS provider hook scripts for DNS-01 validation
+- **`bin/getssl`** — Legacy getssl client (retained for transition)
+- **`bin/utils/`** — Legacy getssl utilities (retained for transition)
 
 ### CLI Scripts (`bin/`)
 
 All scripts bootstrap via `require_once('Globals.php')` which loads the MikoPBX DI container.
 
-- **`cronRenewCert.php`** — Cron entry point: opens port 80, runs `getssl -a -U -q`, installs cert, closes port 80
-- **`reloadCmd.php`** — Called by getssl after successful cert issuance; installs cert/key into PbxSettings
+- **`cronRenewCert.php`** — Cron entry point: conditionally opens port 80 (HTTP-01 only), runs `acme.sh --cron`, installs cert, closes port 80
+- **`reloadCmd.php`** — Called by acme.sh `--reloadcmd` after successful cert issuance; installs cert/key into PbxSettings
 - **`reloadCron.php`** — Reloads cron configuration when module settings change
 - **`cleanupPort80.php`** — Cron watchdog (runs every minute): calls `AcmeHttpPort::cleanupStale()`
 - **`updateCert.php`** — Manual cert request without nchan (runs synchronously)
 
 ### Frontend (ES6 → Babel → ES5)
 
-- **`public/assets/js/src/module-get-ssl-index.js`** — Form controller: validation, module status toggle, triggers API call to start certificate request, handles async response channel
+- **`public/assets/js/src/module-get-ssl-index.js`** — Form controller: validation, module status toggle, challenge type switching (HTTP-01/DNS-01), dynamic DNS provider credential fields based on `dnsProvidersMeta`, credential collection/restoration (base64 JSON), triggers API call to start certificate request
 - **`public/assets/js/src/module-get-ssl-status-worker.js`** — Real-time progress: EventSource (PBX ≥2024.2.30) or polling fallback, Ace editor for log display, 4-stage processing pipeline (STAGE_1–4)
 
 ### Real-time Updates Flow
 
 1. Browser sends `POST /pbxcore/api/modules/ModuleGetSsl/get-cert` with `X-Async-Response-Channel-Id: module-get-ssl-pub`
-2. Backend opens port 80, generates config, launches getssl, monitors process (120s timeout)
+2. Backend conditionally opens port 80 (HTTP-01 only), prepares acme.sh environment, launches acme.sh, monitors process (120s HTTP-01 / 300s DNS-01)
 3. Progress pushed to nchan channel `module-get-ssl-pub` as JSON with `moduleUniqueId`, `stage`, `stageDetails`, `pid`
 4. Browser subscribes via EventSource (PBX ≥2024.2.30) or polls `check-result` endpoint
-5. Backend closes port 80 in `finally` block
+5. Backend closes port 80 in `finally` block (HTTP-01 only)
+
+### DNS-01 Challenge Flow
+
+1. User selects DNS-01 in the UI, picks a DNS provider, enters API credentials
+2. Credentials stored as base64-encoded JSON in `dnsCredentials` model field
+3. On cert request: credentials decoded to `export VAR='val'; ...` prefix before acme.sh command
+4. acme.sh creates `_acme-challenge` TXT record via DNS provider API, validates, cleans up
+5. No port 80 required — works behind firewalls and NAT
 
 ### Symlinks Created at Runtime
-- `/usr/bin/getssl` → `{moduleDir}/bin/getssl`
-- `/usr/share/getssl` → `{moduleDir}/bin/utils`
-- `/usr/www/sites/.well-known` → `{moduleDir}/db/getssl/.well-known`
+- `/usr/bin/acme.sh` → `{moduleDir}/bin/acme/acme.sh`
+- `/usr/bin/getssl` → `{moduleDir}/bin/getssl` (legacy)
+- `/usr/share/getssl` → `{moduleDir}/bin/utils` (legacy)
+- `/usr/www/sites/.well-known` → `{moduleDir}/db/getssl/.well-known` (HTTP-01 only)
 - `/usr/bin/nslookup` → busybox
 
+### Certificate Storage Paths
+
+acme.sh stores certificates in `{moduleDir}/db/acme/{domain}/`:
+- `fullchain.cer` — full certificate chain
+- `{domain}.key` — private key
+
+Legacy getssl paths (`{moduleDir}/db/getssl/{domain}/`) are checked as fallback.
+
 ## Phalcon Version Compatibility
 
 Always use `MikoPBXVersion` for version-dependent class imports (Di, Validation, Uniqueness, Text, Logger). PBX versions ≥2024.2.30 use Phalcon 5; older versions use Phalcon 4. Do not hardcode Phalcon namespace paths.
@@ -89,5 +118,5 @@ Language files in `Messages/`. Translation keys prefixed with `module_getssl_`.
 - PHP 7.4+ / 8.0+, Phalcon 4 or 5
 - MikoPBX Core framework (`MikoPBX\Common`, `MikoPBX\Core`, `MikoPBX\Modules`, `MikoPBX\AdminCabinet`)
 - jQuery, Semantic UI, Ace Editor (from MikoPBX core frontend)
-- `getssl` ACME client (`bin/getssl`, embedded bash script)
+- `acme.sh` ACME client (`bin/acme/acme.sh`, embedded bash script)
 - Minimum PBX version: 2024.1.114 (from `module.json`)

README.md

@@ -6,20 +6,43 @@
 
 This module automates obtaining and renewing free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for your MikoPBX web interface. After setup, the HTTPS certificate is issued automatically and renewed on schedule — no manual steps required.
 
+## Verification Methods
+
+The module supports two verification methods:
+
+### HTTP-01 (default)
+The classic method — Let's Encrypt verifies domain ownership by making an HTTP request to your server on port 80. Simple setup: just enter your domain name and click save.
+
+**Requirements:** port 80 accessible from the internet. The module opens it temporarily during verification and closes it immediately after.
+
+### DNS-01
+Certificate issuance via your DNS provider's API. No need to open port 80 — works behind firewalls, NAT, and in private networks. Also supports **wildcard certificates** (`*.domain.com`).
+
+**Supported providers (20+):** Cloudflare, Amazon Route53, GoDaddy, DigitalOcean, Hetzner, Yandex Cloud, OVH, Selectel, reg.ru, Beget, Namecheap, Azure DNS, Vultr, DuckDNS, Linode, INWX, DreamHost, deSEC, PowerDNS, ISPConfig, Google Cloud DNS, and any custom provider.
+
+**Setup:** select DNS-01 in the verification method dropdown, choose your DNS provider, enter API credentials, and click save.
+
 ## How It Works
 
-1. You install the module from the MikoPBX module marketplace
-2. Enter your domain name in the module settings and click save
-3. The module requests a certificate from Let's Encrypt, and the progress is shown in real time
-4. Once issued, the certificate is automatically applied to the MikoPBX web interface
+1. Install the module from the MikoPBX module marketplace
+2. Enter your domain name in the module settings
+3. Choose a verification method (HTTP-01 or DNS-01)
+4. For DNS-01 — select your DNS provider and enter API credentials
+5. Click save — the module requests a certificate from Let's Encrypt, progress is shown in real time
+6. Once issued, the certificate is automatically applied to the MikoPBX web interface
 
 Auto-renewal runs on the 1st and 15th of each month. If the certificate is due for renewal, it will be updated automatically.
 
 ## Requirements
 
 - MikoPBX **2024.1.114** or newer
-- A domain name pointing to your PBX public IP address (A record)
-- Port **80** accessible from the internet (required for Let's Encrypt HTTP-01 validation)
+- A domain name pointing to your PBX (A record)
+- **For HTTP-01:** port **80** accessible from the internet
+- **For DNS-01:** API credentials from your DNS provider (no open ports required)
+
+## Technical Details
+
+The module uses [acme.sh](https://github.com/acmesh-official/acme.sh) as the ACME client — a widely used, zero-dependency bash script supporting the full ACME v2 protocol and 150+ DNS providers.
 
 ## Documentation
 

readme.ru.md

@@ -6,20 +6,43 @@
 
 Модуль автоматически получает и обновляет бесплатные SSL-сертификаты от [Let's Encrypt](https://letsencrypt.org/) для веб-интерфейса MikoPBX. После настройки HTTPS-сертификат выпускается автоматически и продлевается по расписанию — никаких ручных действий не требуется.
 
+## Способы проверки
+
+Модуль поддерживает два способа проверки владения доменом:
+
+### HTTP-01 (по умолчанию)
+Классический способ — Let's Encrypt проверяет владение доменом, отправляя HTTP-запрос на ваш сервер на порт 80. Простая настройка: достаточно указать доменное имя и нажать сохранить.
+
+**Требование:** порт 80 должен быть доступен из интернета. Модуль открывает его временно на время проверки и закрывает сразу после.
+
+### DNS-01
+Выпуск сертификата через API вашего DNS-провайдера. Не нужно открывать порт 80 — работает за файрволами, NAT и в закрытых сетях. Также поддерживает **wildcard-сертификаты** (`*.domain.com`).
+
+**Поддерживаемые провайдеры (20+):** Cloudflare, Amazon Route53, GoDaddy, DigitalOcean, Hetzner, Yandex Cloud, OVH, Selectel, reg.ru, Beget, Namecheap, Azure DNS, Vultr, DuckDNS, Linode, INWX, DreamHost, deSEC, PowerDNS, ISPConfig, Google Cloud DNS и любой пользовательский провайдер.
+
+**Настройка:** выберите DNS-01 в выпадающем списке способа проверки, выберите DNS-провайдера, введите API-ключи и нажмите сохранить.
+
 ## Как это работает
 
 1. Установите модуль из маркетплейса модулей MikoPBX
-2. Укажите доменное имя в настройках модуля и нажмите сохранить
-3. Модуль запросит сертификат у Let's Encrypt, прогресс отображается в реальном времени
-4. После выпуска сертификат автоматически применяется к веб-интерфейсу MikoPBX
+2. Укажите доменное имя в настройках модуля
+3. Выберите способ проверки (HTTP-01 или DNS-01)
+4. Для DNS-01 — выберите DNS-провайдера и введите API-ключи
+5. Нажмите сохранить — модуль запросит сертификат у Let's Encrypt, прогресс отображается в реальном времени
+6. После выпуска сертификат автоматически применяется к веб-интерфейсу MikoPBX
 
 Автоматическое продление запускается 1-го и 15-го числа каждого месяца. Если сертификат подлежит обновлению, он будет продлён автоматически.
 
 ## Требования
 
 - MikoPBX версии **2024.1.114** или новее
-- Доменное имя, указывающее на публичный IP-адрес АТС (A-запись)
-- Порт **80**, доступный из интернета (необходим для HTTP-01 валидации Let's Encrypt)
+- Доменное имя, указывающее на вашу АТС (A-запись)
+- **Для HTTP-01:** порт **80**, доступный из интернета
+- **Для DNS-01:** API-ключи от вашего DNS-провайдера (открытые порты не нужны)
+
+## Технические детали
+
+Модуль использует [acme.sh](https://github.com/acmesh-official/acme.sh) в качестве ACME-клиента — широко используемый bash-скрипт без зависимостей, поддерживающий полный протокол ACME v2 и более 150 DNS-провайдеров.
 
 ## Документация