# „Zertifikat anfordern"-Button (Dashboard, On-Demand-TLS auslösen) — Design

**Date:** 2026-06-17 · **Branch:** `feat/v1-foundation` · **Status:** approved

Add a System → Domain & TLS control that lets the operator **explicitly request the Let's-Encrypt
certificate from the dashboard** (with a DNS pre-check and a clear status), for the common case where
a domain was configured (at install or in the dashboard) before its DNS pointed at the server.

## Why this is even needed (current behaviour)
Caddy already issues certificates **on demand**: on the first HTTPS handshake for the configured
(active) panel domain, Caddy asks `app:80/_caddy/ask`, the app approves ONLY the active domain
([routes/web.php:35], [docker/caddy/Caddyfile:19]), and Caddy obtains the cert automatically. So once
DNS points here, the cert is fetched on the first `https://<domain>` visit — no action required, and
it self-heals (Caddy retries on later handshakes until DNS is correct).

The gap is **visibility + control**, not capability: the auto-flow is invisible (the operator can't
tell whether the cert exists without opening `https://` and inspecting), and nothing lets them trigger
it proactively. This feature surfaces a DNS check, a proactive trigger, and a status.

## Trigger mechanism (the core decision — approved)
The app triggers Caddy's on-demand issuance by performing an **internal HTTPS handshake to the `caddy`
service with SNI = the domain**:
```
curl --connect-to <domain>:443:caddy:443  https://<domain>/up   (cert-verifying)
```
`--connect-to` keeps SNI/Host = the real domain while dialing the internal `caddy` service (same Docker
network, [docker-compose.prod.yml] `caddy` + `app` share a network). Caddy sees SNI=domain → on-demand
path → asks `/_caddy/ask` (approves) → runs ACME. The ACME challenge itself still needs the PUBLIC
domain to resolve here with 80/443 reachable — the trigger starts issuance, public reachability
completes it. (Rejected alternatives: passive status-only — doesn't actively trigger; exposing Caddy's
admin API — extra attack surface.)

The app image has `curl`, `openssl`, and PHP `dns_get_record` (verified), so no new dependency.

## Flow on click — `DeploymentService::requestCertificate(string $domain): array`
1. **Guard:** if `externalTls()` or the domain is empty → return a `not_applicable` status (the button
   is hidden in those cases anyway; this is belt-and-suspenders).
2. **DNS pre-check** (`domainResolvesHere`): resolve the domain's A/AAAA via `dns_get_record` and
   compare to the server's public IP (`serverPublicIp()`). On a clear mismatch → return
   `status: 'dns_mismatch'` with the resolved-vs-server IPs and DO NOT trigger ACME (this is what
   protects the Let's-Encrypt failed-validation rate limit from being burned). If the public IP can't
   be determined, skip the comparison and proceed (the trigger result is the real source of truth).
3. **Trigger:** the `curl --connect-to <domain>:443:caddy:443 https://<domain>/` handshake (short
   timeout, ~15s). The certificate is established during the TLS handshake itself, so the HTTP path is
   irrelevant — `/` (which redirects to login) is fine; no special endpoint is required.
4. **Verify:** confirm a *trusted* cert is now served for the domain (the cert-verifying curl returns
   2xx/3xx, or an `openssl s_client` check shows a valid chain). → `status: 'issued'`. Otherwise
   `status: 'failed'` with a hint ("Ports 80/443 vom Internet erreichbar? ACME-Challenge fehlgeschlagen.").

### Supporting `DeploymentService` methods
- `serverPublicIp(): ?string` — the server's public IP (`curl -fsS https://api.ipify.org`, ~3s timeout,
  cached ~5 min). Mirrors the installer's approach. Best-effort; null on failure.
- `domainResolvesHere(string $domain): array{ok: ?bool, resolved: string[], serverIp: ?string}` —
  A/AAAA vs public IP. `ok`: true = matches, false = clear mismatch, **null = unknown** (public IP not
  determinable → caller treats unknown as "proceed", since the handshake result is authoritative).

**Status display — persisted, NOT a live page-load probe.** A naive "is a cert active?" check would
itself be an internal handshake for the domain, which (if no cert exists) makes Caddy attempt on-demand
issuance — so auto-probing on every page load could burn the ACME failed-validation rate limit when DNS
is wrong. Instead, `requestCertificate()` **persists its outcome** (a `Setting` `tls_cert_status`:
`{status, checkedAt, detail}`); the System page reads that persisted value for the status line ("zuletzt
geprüft … — ausgestellt ✓ / DNS zeigt woanders / ausstehend", or "noch nicht geprüft"). Only the button
performs a live check. No page-load side effects, no surprise ACME calls.

## UI — `System/Index` (Domain & TLS panel)
- A **TLS-Zertifikat** status line + a **„DNS prüfen & Zertifikat anfordern"** button.
- **Visible only** when `tlsMode === 'caddy'` AND an **active** domain exists AND not bare-IP. In
  **external** TLS mode show a short note instead ("Zertifikat über den externen Reverse-Proxy"); on a
  bare IP / no domain, omit the row.
- The button is a direct server action with a **`wire:loading` spinner** (the trigger is slow: DNS +
  handshake + ACME). Result surfaced via the existing toaster (`notify`, with `level: 'error'` on
  failure) and a refreshed status line.
- **Pending-domain nuance:** the button operates on the **active** domain (what Caddy serves). If a
  domain change is saved but awaiting a restart (`configuredDomain() !== domain()`), show the existing
  "restart to apply" hint and act on the active domain (or disable until restarted) — never imply a cert
  can be issued for a not-yet-active domain.
- German copy, no emoji (R16); only `@theme` token utilities (R3); no inline styles (R4).

## Abuse / rate-limiting (fits the just-shipped hardening)
`requestCertificate` is an authenticated admin action but it triggers outbound ACME, so throttle it
**per user**: `RateLimiter` key `cert-request:<id>`, e.g. **5 / 10 min**, auto-expiring (never a
control-plane lockout). The DNS pre-check additionally avoids triggering ACME when DNS is obviously
wrong. Audit the request (`AuditEvent`, action `tls.cert_request`).

## Constraints honoured
- **Control plane never locked out:** no new permanent state; the throttle auto-expires; bare-IP
  recovery + `clusev:reset-admin` untouched.
- **No cert-issuance abuse:** `/_caddy/ask` still approves only the active domain; the per-user throttle
  + DNS pre-check bound ACME calls.
- **External-TLS mode** is respected (button hidden; Caddy issues nothing there).

## Files
- `app/Services/DeploymentService.php` — `serverPublicIp`, `domainResolvesHere`, `requestCertificate`
  (the latter persists `tls_cert_status`). No live page-load cert probe (see status note above).
- `app/Livewire/System/Index.php` — `requestCertificate()` action (throttled + audited; persists the
  outcome to `Setting` `tls_cert_status`), a status property read from that Setting, visibility gating.
- `resources/views/livewire/system/index.blade.php` — status line + button (loading spinner), mode gating.
- `lang/{de,en}/system.php` — status/button/result strings.
- Tests: `domainResolvesHere` match/mismatch/unknown; `requestCertificate` state machine (dns_mismatch /
  issued / failed) with the curl + IP lookups mocked; the throttle.

## Testing
- Unit: mock DNS + public IP → assert `domainResolvesHere` ok/mismatch/unknown; assert
  `requestCertificate` returns `dns_mismatch` WITHOUT triggering the handshake on a mismatch, and the
  throttle blocks after the cap.
- R12 browser: the status line + button render in caddy mode with an active domain; hidden in external
  mode / bare IP; the spinner shows on click. (Real ACME issuance can only be confirmed on a host with
  correct public DNS — verify the UI states + the no-trigger-on-mismatch path.)
- Pint, full suite green, Codex clean (no errors / security issues — especially no SSRF via the domain
  string: the handshake target is pinned to the `caddy` service via `--connect-to`, and the domain is
  the operator-validated panel domain, not arbitrary user input).

## Out of scope
- Moving long SSH operations off the request path (separate UX/perf item).
- Cert renewal UI (Caddy renews automatically; on-demand re-issues as needed).
- Manual cert upload / custom CA.
