release: v0.13.0 — shimkit tls --method dns-cloudflare

imanimanyara · imanimanyara · commit 21e2b70334cf · 2026-05-16T01:18:38.000-04:00
DNS-01 ACME challenge via Cloudflare. The path to wildcard certs
(`*.example.com`) — Let's Encrypt only issues those via DNS-01.

Surface (additive — webroot path unchanged):

    shimkit tls request --method dns-cloudflare \
        --credentials FILE -d D -d '*.D' ...

Auto-selects the `certbot/dns-cloudflare:v3.0.1` image. Webroot
method still uses `certbot/certbot:v3.0.1`.

Setup:

  echo 'dns_cloudflare_api_token = TOKEN' &gt; ~/.secrets/cloudflare.ini
  chmod 600 ~/.secrets/cloudflare.ini   # mandatory — both shimkit
                                          # and certbot refuse
                                          # group/world-readable

The parent directory of the credentials file is mounted at
`/credentials` inside the container, read-only. shimkit catches
the mode check up-front with a clearer message than certbot.

Cloudflare-only today. Other DNS providers (Route53,
DigitalOcean, Hurricane Electric, etc.) each need their own
credential surface and a different `certbot/dns-&lt;provider&gt;`
image. Opt-in extras in a future release.

Implementation:

- `certbot.request_argv` widened to `method: Literal["webroot",
  "dns-cloudflare"]`. The DNS path adds the four
  `--dns-cloudflare*` flags including the propagation-seconds knob.
- `certbot.container_volumes` accepts an optional `credentials`
  Path and mounts its parent at `/credentials:ro`.
- `manager.request` chooses image based on method; runs the per-
  method preflight (webroot dir vs credentials-file mode 0600).
- `_is_valid_domain` accepts a leading `*.` (wildcard required by
  DNS-01).
- New `tools.tls.{certbot_dns_cloudflare_image,
  cloudflare_propagation_seconds}` config fields. Propagation has
  `Field(ge=0, le=600)`.

Tests: 17 new in test_tools_tls_dns_cloudflare.py (1027 → 1044
total). Pure argv-builder shape (DNS flags + propagation +
staging/dry-run; webroot path unaffected), container_volumes with
+ without credentials mount, manager validation (missing-
credentials refusal / missing-file refusal / loose-mode refusal /
happy path picks dns-cloudflare image and mounts credentials
parent / JSON output includes method), config plumbing
(propagation_seconds range validation incl. negative-value
rejection).

Gates: pytest 1044 passed, ruff clean, mypy strict clean. No new
optional dependency extras.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,61 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.13.0] — 2026-05-16
+
+### Added
+
+- `shimkit tls request --method dns-cloudflare` — DNS-01 ACME
+  challenge via Cloudflare. Required for wildcard certs (`*.example.com`).
+  Uses the upstream `certbot/dns-cloudflare:v3.0.1` image (auto-
+  selected when `--method dns-cloudflare` is passed; the webroot
+  method still uses `certbot/certbot:v3.0.1`).
+- `--credentials PATH` flag on `tls request`. Points at a file
+  containing `dns_cloudflare_api_token = <token>` (one line).
+  Manager refuses the file when mode isn't 0600 — certbot also
+  refuses, but shimkit catches it earlier with a clearer message.
+  Parent directory of the file is mounted at `/credentials`
+  inside the container read-only.
+- `tools.tls.certbot_dns_cloudflare_image` config field — pin the
+  DNS plugin image independently of the webroot image.
+- `tools.tls.cloudflare_propagation_seconds` config field —
+  default `60`, range `[0, 600]`. Lower it on accounts with fast
+  Cloudflare propagation; raise for slow zones.
+
+### Changed
+
+- `_is_valid_domain` accepts a leading `*.` for wildcard domains
+  (required by DNS-01). The rest of the domain validates as before.
+- `tls request` `--webroot` is now optional — required for the
+  webroot method but not for dns-cloudflare. The error message
+  guides the user to the right flag combination for each method.
+- `TlsConfig.default_method` widened from `Literal["webroot"]` to
+  `Literal["webroot", "dns-cloudflare"]`.
+
+### Tests
+
+- 17 new tests in `tests/test_tools_tls_dns_cloudflare.py` (1027 →
+  1044 total). Pure argv-builder shape (DNS flags + propagation +
+  staging/dry-run combos; webroot path unaffected), container_volumes
+  with + without credentials mount, manager validation
+  (missing-credentials refusal / missing-file refusal / loose-mode
+  refusal / happy path picks dns-cloudflare image and mounts
+  credentials parent dir / JSON output includes method), config
+  plumbing (cloudflare_propagation_seconds range validation).
+
+### Notes
+
+DNS-01 is the only ACME path that supports wildcard certs. The
+plugin image is ~70MB so the first `tls request --method
+dns-cloudflare` pulls it; subsequent runs are local.
+
+Cloudflare-only today. Other DNS providers (Route53,
+DigitalOcean, etc.) each need their own credential surface — opt-
+in extras in a future release.
+
+Gates: pytest 1044 passed, ruff clean, mypy strict clean. No new
+optional dependency extras (reuses `[docker-clean]`'s `docker`).
+
 ## [0.12.0] — 2026-05-15
 
 ### Changed
diff --git a/docs/README.md b/docs/README.md
@@ -91,6 +91,8 @@ Top-level utilities (not tools):
 
 Per-version, user-facing summaries (newest first):
 
+- **[`v0.13.0`](release-notes/v0.13.0.md)** — `shimkit tls --method
+  dns-cloudflare` for DNS-01 + wildcard certs.
 - **[`v0.12.0`](release-notes/v0.12.0.md)** — stale-doc cleanup +
   codecov upload + `gh attestation verify` smoke. No code changes.
 - **[`v0.11.0`](release-notes/v0.11.0.md)** — docs consolidation +
diff --git a/docs/release-notes/v0.13.0.md b/docs/release-notes/v0.13.0.md
@@ -0,0 +1,157 @@
+# shimkit 0.13.0
+
+`shimkit tls --method dns-cloudflare` — DNS-01 ACME challenge via
+Cloudflare. The path to wildcard certs (`*.example.com`). For the
+full machine-readable changelog, see
+[`CHANGELOG.md`](../../CHANGELOG.md).
+
+---
+
+## TL;DR
+
+```
+shimkit tls request --method dns-cloudflare --credentials FILE -d ...
+```
+
+Uses `certbot/dns-cloudflare:v3.0.1` (auto-selected). Webroot
+method still uses `certbot/certbot:v3.0.1` — the two paths are
+independent and you can mix-and-match by domain.
+
+---
+
+## Why DNS-01
+
+The webroot (HTTP-01) method that shipped in v0.8.0 works for
+single hostnames you control via HTTP. But **wildcard certs
+(`*.example.com`) only work via DNS-01** — that's a Let's Encrypt
+constraint, not a shimkit one.
+
+DNS-01 also works for domains where you don't (or can't) terminate
+HTTP locally — internal-only services, mail hosts, anything behind
+a load balancer that doesn't forward `/.well-known/acme-challenge/`.
+
+---
+
+## Setup
+
+1. **Create a Cloudflare API token** with `Zone:DNS:Edit` scope on
+   the zone you're issuing for. <https://dash.cloudflare.com/profile/api-tokens>.
+   (Don't use the legacy "Global API Key" — that's account-wide.)
+
+2. **Write the credentials file**:
+
+   ```bash
+   echo 'dns_cloudflare_api_token = YOUR-CLOUDFLARE-API-TOKEN' \
+       > ~/.secrets/cloudflare.ini
+   chmod 600 ~/.secrets/cloudflare.ini
+   ```
+
+   Mode 0600 is mandatory — both shimkit and certbot refuse the
+   file if it's group- or world-readable.
+
+3. **Issue the cert** (staging first; production rate limits are
+   punishing):
+
+   ```bash
+   shimkit tls request --yes --staging \
+       --email ops@example.com \
+       --method dns-cloudflare \
+       --credentials ~/.secrets/cloudflare.ini \
+       -d example.com -d '*.example.com'
+   ```
+
+4. Once staging works, drop `--staging` for the real cert.
+
+---
+
+## How it works
+
+```
+docker run --rm \
+  -v ~/.shimkit/data/tls/etc-letsencrypt:/etc/letsencrypt \
+  -v ~/.shimkit/data/tls/var-lib-letsencrypt:/var/lib/letsencrypt \
+  -v ~/.secrets:/credentials:ro \
+  certbot/dns-cloudflare:v3.0.1 \
+  certonly --non-interactive --agree-tos \
+  --email ops@example.com \
+  --dns-cloudflare \
+  --dns-cloudflare-credentials /credentials/cloudflare.ini \
+  --dns-cloudflare-propagation-seconds 60 \
+  -d example.com -d '*.example.com'
+```
+
+The parent directory of the credentials file gets mounted at
+`/credentials` inside the container, so
+`~/.secrets/cloudflare.ini` on the host becomes
+`/credentials/cloudflare.ini` inside.
+
+Cloudflare's plugin uses the API token to write the
+`_acme-challenge.<domain>` TXT record, waits the configured
+propagation seconds (default 60), then asks the ACME CA to
+validate.
+
+---
+
+## What's new
+
+| | |
+|---|---|
+| `--method webroot` | (default) HTTP-01 via local webserver |
+| `--method dns-cloudflare` | DNS-01 via Cloudflare API |
+| `--credentials PATH` | Cloudflare creds file (mode 0600 required) |
+| `tools.tls.cloudflare_propagation_seconds` | Default `60`, range `[0, 600]` |
+| `tools.tls.certbot_dns_cloudflare_image` | Pinned `certbot/dns-cloudflare:v3.0.1` |
+
+Wildcards (`*.example.com`) now validate in shimkit's domain check
+— previously only single-label-then-dot patterns were accepted.
+
+---
+
+## Renewal
+
+DNS-01 certs renew the same way as webroot certs:
+
+```bash
+shimkit tls renew --yes
+```
+
+The `renew` command doesn't need `--method`, `--credentials`, or
+`--webroot` — certbot reads each cert's renewal config from
+`/etc/letsencrypt/renewal/<domain>.conf` (written at issuance
+time) and reuses the same method.
+
+The daily renewal cron from v0.8.0 covers both methods.
+
+---
+
+## Limits
+
+- **Cloudflare-only today.** Other DNS providers (Route53,
+  DigitalOcean, Hurricane Electric, etc.) each need their own
+  credential surface and a different `certbot/dns-<provider>`
+  image. Opt-in extras in a future release.
+- **Token, not key.** Use a scoped API token (`Zone:DNS:Edit` on
+  the zone), not the legacy Global API Key. The Global API Key is
+  account-wide and gives the credentials file far more power than
+  cert issuance needs.
+
+---
+
+## Stats
+
+- Tests: 1027 → 1044 (+17)
+- Gates: pytest, ruff, mypy strict — all green
+- New optional extras: 0
+
+---
+
+## Upgrading
+
+```bash
+uv tool upgrade shimkit
+pipx upgrade shimkit
+```
+
+Existing webroot users see no behavioural change. To start using
+DNS-01, add the credentials file + pass `--method dns-cloudflare
+--credentials`.
diff --git a/docs/tools/tls.md b/docs/tools/tls.md
@@ -24,7 +24,9 @@ flags after (`--json`, `--dry-run`, `--yes`, `--force`).
 
 ## How it works
 
-`shimkit tls request` runs:
+### Webroot (HTTP-01, default)
+
+`shimkit tls request --method webroot` runs:
 
 ```
 docker run --rm \
@@ -39,6 +41,45 @@ docker run --rm \
   [--staging]
 ```
 
+### DNS-cloudflare (DNS-01, v0.13.0+)
+
+`shimkit tls request --method dns-cloudflare` runs:
+
+```
+docker run --rm \
+  -v ~/.shimkit/data/tls/etc-letsencrypt:/etc/letsencrypt \
+  -v ~/.shimkit/data/tls/var-lib-letsencrypt:/var/lib/letsencrypt \
+  -v <credentials-parent-dir>:/credentials:ro \
+  certbot/dns-cloudflare:v3.0.1 \
+  certonly --non-interactive --agree-tos \
+  --email ops@example.com \
+  --dns-cloudflare \
+  --dns-cloudflare-credentials /credentials/cloudflare.ini \
+  --dns-cloudflare-propagation-seconds 60 \
+  -d example.com [-d '*.example.com'] \
+  [--staging]
+```
+
+**Required for wildcards.** `*.example.com` certs only work via
+DNS-01. The Cloudflare plugin needs a Cloudflare API token with
+`Zone:DNS:Edit` scope on the zone you're issuing for.
+
+**Credentials file format** (one line):
+
+```ini
+dns_cloudflare_api_token = your-cloudflare-api-token-here
+```
+
+**Mode 0600 required.** certbot refuses any credentials file that's
+group- or world-readable; shimkit refuses up-front with a clear
+error before invoking the container. Run `chmod 600 cloudflare.ini`
+before passing it.
+
+The parent directory of the credentials file is mounted at
+`/credentials` inside the container, read-only. So
+`/secrets/cloudflare.ini` on the host becomes
+`/credentials/cloudflare.ini` inside.
+
 The webroot must already be served at
 `http://<domain>/.well-known/acme-challenge/` for the ACME challenge
 to succeed. The recommended layout for `shimkit web nginx vhost`-
@@ -68,8 +109,9 @@ renewal, so nginx never needs to be told a new cert path.
 ## Examples
 
 ```bash
-# Request a cert in staging first (recommended — Let's Encrypt
-# rate-limits production aggressively, but staging is forgiving).
+# Webroot (HTTP-01) — Request a cert in staging first (recommended —
+# Let's Encrypt rate-limits production aggressively, but staging is
+# forgiving).
 shimkit tls request --yes --staging \
     --email ops@example.com \
     --webroot /var/www/example \
@@ -81,6 +123,15 @@ shimkit tls request --yes \
     --webroot /var/www/example \
     -d example.com -d www.example.com
 
+# DNS-cloudflare (DNS-01) — required for wildcards.
+echo 'dns_cloudflare_api_token = YOUR-TOKEN-HERE' > ~/.secrets/cloudflare.ini
+chmod 600 ~/.secrets/cloudflare.ini
+shimkit tls request --yes --staging \
+    --email ops@example.com \
+    --method dns-cloudflare \
+    --credentials ~/.secrets/cloudflare.ini \
+    -d example.com -d '*.example.com'
+
 # Enumerate local certs.
 shimkit tls list
 shimkit tls list --json
@@ -156,10 +207,11 @@ in `tls list` / `tls status` (which shells out to `openssl x509
   punishing (5 failed validations / hour / hostname). Always
   pass `--staging` for first runs; the resulting cert isn't
   trusted but proves the webroot setup works.
-- **Webroot vs DNS-01.** Only webroot is wired today. DNS-01
-  (required for wildcard certs) lands as opt-in extras in a
-  future release — each provider needs its own credential
-  surface (`cloudflare`, `route53`, etc.).
+- **Webroot vs DNS-01.** Both are wired as of v0.13.0. Webroot
+  (HTTP-01) is the default; DNS-01 via Cloudflare is opt-in via
+  `--method dns-cloudflare` and is the **only** path to wildcard
+  certs. Other DNS providers (Route53, DigitalOcean, etc.) each
+  need their own credential surface and are deferred.
 - **No PyPI extra.** This tool reuses the `[docker-clean]`
   extra's `docker` package — no new install footprint.
 - **Renewal cadence.** Let's Encrypt certs are valid for 90 days;
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shimkit"
-version = "0.12.0"
+version = "0.13.0"
 description = "A toolkit of developer utilities — Java version manager, shell upgrader, and more. Python tools, shimmed by bash."
 readme = "README.md"
 license = { file = "LICENSE" }
diff --git a/src/shimkit/__init__.py b/src/shimkit/__init__.py
@@ -3,5 +3,5 @@
 Python tools, shimmed by bash.
 """
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"
 __all__ = ["__version__"]
diff --git a/src/shimkit/config/defaults.json b/src/shimkit/config/defaults.json
@@ -193,7 +193,9 @@
     "tls": {
       "data_dir": "~/.shimkit/data/tls",
       "certbot_image": "certbot/certbot:v3.0.1",
+      "certbot_dns_cloudflare_image": "certbot/dns-cloudflare:v3.0.1",
       "default_method": "webroot",
+      "cloudflare_propagation_seconds": 60,
       "default_email": null,
       "renewal_schedule": "17 3 * * *",
       "revoke_severe_token": "REVOKE-TLS"
diff --git a/src/shimkit/config/schema.py b/src/shimkit/config/schema.py
@@ -382,13 +382,20 @@ class TlsConfig(_StrictModel):
 
     # Volume root for /etc/letsencrypt content. Persists across renewals.
     data_dir: str = "~/.shimkit/data/tls"
-    # Certbot image to run one-shot. Pin to a known-good version rather
-    # than `:latest` so a registry-side image change can't break renewals
-    # silently.
+    # Certbot image used for webroot challenges. Pin to a known-good
+    # version rather than `:latest` so a registry-side image change
+    # can't break renewals silently.
     certbot_image: str = "certbot/certbot:v3.0.1"
-    # Default ACME challenge method. Only `webroot` is wired today;
-    # `dns-cloudflare` etc. land as opt-in extras in a later release.
-    default_method: Literal["webroot"] = "webroot"
+    # Certbot image with the dns-cloudflare plugin pre-installed.
+    # Used when `--method dns-cloudflare` is passed.
+    certbot_dns_cloudflare_image: str = "certbot/dns-cloudflare:v3.0.1"
+    # Default ACME challenge method. `webroot` (HTTP-01) is the
+    # original; `dns-cloudflare` (DNS-01) lands in v0.13.0 and is the
+    # path to wildcard certs.
+    default_method: Literal["webroot", "dns-cloudflare"] = "webroot"
+    # Cloudflare DNS propagation seconds. The plugin's recommended
+    # baseline; safe to lower on accounts with fast propagation.
+    cloudflare_propagation_seconds: int = Field(default=60, ge=0, le=600)
     # ACME account email. Required by Let's Encrypt for issuance unless
     # `--register-unsafely-without-email` is passed (we don't expose
     # that flag). User config overrides per-install.
diff --git a/src/shimkit/tools/tls/certbot.py b/src/shimkit/tools/tls/certbot.py
diff --git a/src/shimkit/tools/tls/commands.py b/src/shimkit/tools/tls/commands.py
diff --git a/src/shimkit/tools/tls/manager.py b/src/shimkit/tools/tls/manager.py
diff --git a/tests/test_tools_tls_dns_cloudflare.py b/tests/test_tools_tls_dns_cloudflare.py
