Add ACME HTTP-01 failure hints

Author: eldryoth

CHANGELOG.md

@@ -9,6 +9,14 @@ behavior when the change improves security or project direction.
 
 ## Unreleased
 
+### Added
+
+- Route-scoped cache runtime stats now appear in the protected admin cache
+  status endpoint and activity-reset response.
+- ACME HTTP-01 client failures now include published challenge URLs after
+  challenge material has been written, making failed authorization checks easier
+  to debug from production logs.
+
 ## 1.1.0 - TLS Policy And Certificate Operations
 
 Released: pending

ROADMAP.md

@@ -234,7 +234,10 @@ These are realistic additions to implement across the stable core and early
    - Improve ACME command output for production runs: report per-target
      `skipped`, `renewed`, and `failed` status, include domain/order context
      on issuer failures, and print the HTTP-01 challenge path/URL when an
-     authorization fails.
+     authorization fails. Implemented for target statuses, per-target
+     success/failure lines, due-only status messaging, and HTTP-01 URL context
+     after challenge files are published. Planned: richer issuer
+     authorization/order context when the client library exposes it cleanly.
    - Add native systemd deployment support before `1.0.0`: a hardened
      `fluxheim.service`, optional environment file, tmpfiles/sysusers
      guidance, documented install paths, config validation before start, and

docs/certificate-renewal.md

@@ -163,8 +163,10 @@ with `acme attempted: 0` and a status message saying no certificates are due.
 First issuance normally does not need `--force-renew`: missing certificate files
 are due targets. The command prints every target with `status=due`,
 `status=skipped`, or `status=forced`, then reports per-target `renewed:` and
-`failed:` lines. It exits non-zero if any target failed, while still reporting
-successful renewals from the same run.
+`failed:` lines. For HTTP-01 failures after challenge files are published, the
+failure includes `published_http_01=` URLs so operators can test the exact public
+challenge paths that the issuer should have reached. It exits non-zero if any
+target failed, while still reporting successful renewals from the same run.
 
 Use `--force-renew` only for deliberate emergency rotation or testing when you
 really need to reissue certificates that are still valid; repeated forced

src/acme.rs

@@ -531,7 +531,11 @@ pub fn execute_renewal<Client: AcmeIssuerClient>(
             .finalize_http_01_order(&order, &challenge_store)
             .map_err(|error| AcmeRenewalError::Client {
                 issuer: item.target.issuer.clone(),
-                message: error.to_string(),
+                message: acme_client_error_message_with_http_01_context(
+                    error,
+                    &item.target.domains,
+                    &published,
+                ),
             })?;
         let certificate = install_managed_certificate(
             storage,
@@ -713,7 +717,11 @@ async fn execute_instant_http_01_renewal(
                     .await
                     .map_err(|error| AcmeRenewalError::Client {
                         issuer: item.target.issuer.clone(),
-                        message: error.to_string(),
+                        message: acme_client_error_message_with_http_01_context(
+                            error,
+                            &item.target.domains,
+                            &published,
+                        ),
                     })?;
             }
         }
@@ -724,15 +732,23 @@ async fn execute_instant_http_01_renewal(
             .await
             .map_err(|error| AcmeRenewalError::Client {
                 issuer: item.target.issuer.clone(),
-                message: error.to_string(),
+                message: acme_client_error_message_with_http_01_context(
+                    error,
+                    &item.target.domains,
+                    &published,
+                ),
             })?;
         let private_key_pem = Zeroizing::new(
             order
                 .finalize()
                 .await
                 .map_err(|error| AcmeRenewalError::Client {
                     issuer: item.target.issuer.clone(),
-                    message: error.to_string(),
+                    message: acme_client_error_message_with_http_01_context(
+                        error,
+                        &item.target.domains,
+                        &published,
+                    ),
                 })?
                 .into_bytes(),
         );
@@ -741,7 +757,11 @@ async fn execute_instant_http_01_renewal(
             .await
             .map_err(|error| AcmeRenewalError::Client {
                 issuer: item.target.issuer.clone(),
-                message: error.to_string(),
+                message: acme_client_error_message_with_http_01_context(
+                    error,
+                    &item.target.domains,
+                    &published,
+                ),
             })?
             .into_bytes();
         let certificate = install_managed_certificate(
@@ -1290,6 +1310,31 @@ fn cleanup_http_01_challenges(
     Ok(())
 }
 
+fn acme_client_error_message_with_http_01_context(
+    error: impl fmt::Display,
+    domains: &[String],
+    tokens: &[String],
+) -> String {
+    let message = error.to_string();
+    let urls = http_01_challenge_urls(domains, tokens);
+    if urls.is_empty() {
+        return message;
+    }
+    format!("{message}; published_http_01={}", urls.join(","))
+}
+
+fn http_01_challenge_urls(domains: &[String], tokens: &[String]) -> Vec<String> {
+    let mut urls = Vec::new();
+    for domain in domains {
+        for token in tokens {
+            urls.push(format!(
+                "http://{domain}/.well-known/acme-challenge/{token}"
+            ));
+        }
+    }
+    urls
+}
+
 #[cfg(feature = "acme-client")]
 fn cleanup_tls_alpn_01_challenges(
     store: &AcmeTlsAlpn01ChallengeStore,
@@ -3116,6 +3161,9 @@ mod tests {
         let error = execute_renewal(&config, &item, &mut client).unwrap_err();
 
         assert!(matches!(error, AcmeRenewalError::Client { .. }));
+        assert!(error.to_string().contains(
+            "published_http_01=http://example.test/.well-known/acme-challenge/token_123"
+        ));
         assert_eq!(client.finalize_calls, 1);
         let store = AcmeHttp01ChallengeStore::new(&storage, "example");
         assert_eq!(store.load_key_authorization("token_123").unwrap(), None);
@@ -3124,6 +3172,21 @@ mod tests {
         assert!(!paths.key_path.exists());
     }
 
+    #[test]
+    fn http_01_error_context_lists_all_published_urls() {
+        let message = super::acme_client_error_message_with_http_01_context(
+            "authorization failed",
+            &["example.test".to_owned(), "www.example.test".to_owned()],
+            &["token-a".to_owned(), "token-b".to_owned()],
+        );
+
+        assert!(message.starts_with("authorization failed; published_http_01="));
+        assert!(message.contains("http://example.test/.well-known/acme-challenge/token-a"));
+        assert!(message.contains("http://example.test/.well-known/acme-challenge/token-b"));
+        assert!(message.contains("http://www.example.test/.well-known/acme-challenge/token-a"));
+        assert!(message.contains("http://www.example.test/.well-known/acme-challenge/token-b"));
+    }
+
     #[test]
     fn eab_file_secrets_are_trimmed_bounded_and_redacted() {
         let root = crate::test_support::unique_temp_path("acme-eab-file-secrets");