fix: poll DNS for challenge TXT visibility before ACME validation

Replaces the hardcoded 5s challengePropagationDelayMs sleep (too short for
_acme-challenge TXT records to reach Let's Encrypt's validators, causing
DNS problem: NXDOMAIN failures) with active polling: query both a public
resolver (1.1.1.1) and the zone's authoritative nameservers for the exact
challenge value, proceeding once either is satisfied, with a bounded
per-query timeout so a hung resolver can't hang the whole issuance flow.
Configurable via ACME_PROPAGATION_DELAY_MS / ACME_PROPAGATION_TIMEOUT_MS.

Author: samgbafa

.env.example

@@ -14,6 +14,10 @@ ACME_EMAIL=ops@tinycloud.xyz
 # only once the service has been validated end-to-end:
 #   https://acme-v02.api.letsencrypt.org/directory
 ACME_DIRECTORY=https://acme-staging-v02.api.letsencrypt.org/directory
+# How long to wait before the first DNS-01 propagation check, and how long to keep polling
+# before giving up. Defaults: 10000ms / 120000ms.
+ACME_PROPAGATION_DELAY_MS=
+ACME_PROPAGATION_TIMEOUT_MS=
 
 # TEE attestation document (Phala dstack), optional outside of TEE deployments
 ATTESTATION_DOCUMENT=

src/acme.test.ts

@@ -14,6 +14,7 @@ test("issues a certificate via DNS-01 using a fake acme-client and in-memory DNS
     email: "ops@tinycloud.xyz",
     dnsProvider,
     clientFactory: () => fakeClient,
+    checkPropagation: async () => {},
   });
 
   const domain = "mynode.local.tinycloud.link";
@@ -43,6 +44,7 @@ test("cleans up the DNS-01 TXT record even if the ACME order fails", async () =>
     email: "ops@tinycloud.xyz",
     dnsProvider,
     clientFactory: () => fakeClient,
+    checkPropagation: async () => {},
   });
 
   const domain = "failingnode.local.tinycloud.link";
@@ -51,3 +53,28 @@ test("cleans up the DNS-01 TXT record even if the ACME order fails", async () =>
   await assert.rejects(() => issuer.issueCertificate({ csrPem: csr, domain }));
   assert.equal(dnsProvider.txtRecords.size, 0);
 });
+
+test("cleans up the DNS-01 TXT record and never completes the challenge if propagation never becomes visible", async () => {
+  const dnsProvider = new InMemoryDnsProvider();
+  const fakeClient = new FakeAcmeClient();
+  const issuer = new DnsO1AcmeIssuer({
+    directoryUrl: "https://fake-acme.test/directory",
+    accountKeyPem: "fake-account-key",
+    email: "ops@tinycloud.xyz",
+    dnsProvider,
+    clientFactory: () => fakeClient,
+    checkPropagation: async () => {
+      throw new Error("timed out after 120000ms waiting for TXT record to propagate");
+    },
+  });
+
+  const domain = "unpropagated.local.tinycloud.link";
+  const csr = createTestCsr(domain);
+
+  await assert.rejects(
+    () => issuer.issueCertificate({ csrPem: csr, domain }),
+    /timed out.*propagate/
+  );
+  assert.equal(fakeClient.completedChallenges.length, 0);
+  assert.equal(dnsProvider.txtRecords.size, 0);
+});

src/acme.ts

@@ -1,6 +1,7 @@
 import { X509Certificate } from "node:crypto";
 import * as acme from "acme-client";
 import type { DnsProvider } from "./dns/provider.js";
+import { waitForTxtPropagation } from "./dns/propagation.js";
 
 export interface AcmeIssueResult {
   certChainPem: string;
@@ -63,8 +64,12 @@ export interface DnsO1AcmeIssuerOptions {
   email: string;
   dnsProvider: DnsProvider;
   clientFactory?: AcmeClientFactory;
-  /** Delay after publishing the DNS-01 TXT record, before asking the CA to validate. */
-  challengePropagationDelayMs?: number;
+  /**
+   * Confirms the _acme-challenge TXT record is actually visible in DNS before asking the CA to
+   * validate it. Defaults to polling real DNS (see ./dns/propagation.ts); tests inject a fake to
+   * avoid network calls.
+   */
+  checkPropagation?: (recordName: string, expectedValue: string) => Promise<void>;
 }
 
 /** Issues a certificate via ACME DNS-01, brokering the challenge through a DnsProvider. */
@@ -104,9 +109,7 @@ export class DnsO1AcmeIssuer implements AcmeIssuer {
         const record = await this.opts.dnsProvider.createTxtRecord(recordName, keyAuthorization);
         cleanups.push(() => this.opts.dnsProvider.deleteTxtRecord(recordName, record.id));
 
-        if (this.opts.challengePropagationDelayMs) {
-          await sleep(this.opts.challengePropagationDelayMs);
-        }
+        await (this.opts.checkPropagation ?? waitForTxtPropagation)(recordName, keyAuthorization);
 
         await client.completeChallenge(challenge);
         await client.waitForValidStatus(challenge);
@@ -125,10 +128,6 @@ export class DnsO1AcmeIssuer implements AcmeIssuer {
   }
 }
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 function extractNotAfter(certChainPem: string): string {
   const leafEnd = certChainPem.indexOf("-----END CERTIFICATE-----");
   const leafPem =

src/dns-propagation.test.ts

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { waitForTxtPropagation } from "./dns/propagation.js";
+
+const RECORD_NAME = "_acme-challenge.example.local.tinycloud.link";
+const EXPECTED_VALUE = "expected-value";
+
+/** Deterministic fake clock: sleep() advances the clock instead of waiting in real time. */
+function fakeClock() {
+  let time = 0;
+  return {
+    now: () => time,
+    sleep: async (ms: number) => {
+      time += ms;
+    },
+  };
+}
+
+test("resolves on the first poll when the public resolver already shows the value", async () => {
+  const clock = fakeClock();
+  let publicCalls = 0;
+  let authoritativeFactoryCalls = 0;
+
+  await waitForTxtPropagation(RECORD_NAME, EXPECTED_VALUE, {
+    publicResolver: {
+      resolveTxt: async () => {
+        publicCalls += 1;
+        return [[EXPECTED_VALUE]];
+      },
+    },
+    authoritativeResolverFactory: async () => {
+      authoritativeFactoryCalls += 1;
+      return { resolveTxt: async () => [] };
+    },
+    initialDelayMs: 10000,
+    pollIntervalMs: 2000,
+    timeoutMs: 120000,
+    now: clock.now,
+    sleep: clock.sleep,
+  });
+
+  assert.equal(publicCalls, 1);
+  assert.equal(
+    authoritativeFactoryCalls,
+    0,
+    "authoritative resolver should not be needed once the public resolver already shows the value"
+  );
+});
+
+test("resolves once the authoritative servers have shown the value for the full grace period", async () => {
+  const clock = fakeClock();
+  let authoritativeCalls = 0;
+
+  await waitForTxtPropagation(RECORD_NAME, EXPECTED_VALUE, {
+    publicResolver: { resolveTxt: async () => [] },
+    authoritativeResolverFactory: async () => ({
+      resolveTxt: async () => {
+        authoritativeCalls += 1;
+        return [[EXPECTED_VALUE]];
+      },
+    }),
+    initialDelayMs: 10000,
+    pollIntervalMs: 2000,
+    authoritativeGraceMs: 6000,
+    timeoutMs: 120000,
+    now: clock.now,
+    sleep: clock.sleep,
+  });
+
+  // authoritativeGraceMs (6s) / pollIntervalMs (2s) means the value must be observed across
+  // several successive polls (not just once) before we're willing to proceed on it alone.
+  assert.equal(authoritativeCalls, 4);
+});
+
+test("times out with a clear error when the value never becomes visible anywhere", async () => {
+  const clock = fakeClock();
+
+  await assert.rejects(
+    () =>
+      waitForTxtPropagation(RECORD_NAME, EXPECTED_VALUE, {
+        publicResolver: { resolveTxt: async () => [] },
+        authoritativeResolverFactory: async () => ({ resolveTxt: async () => [] }),
+        initialDelayMs: 1000,
+        pollIntervalMs: 1000,
+        timeoutMs: 5000,
+        now: clock.now,
+        sleep: clock.sleep,
+      }),
+    new RegExp(`timed out after 5000ms waiting for ${RECORD_NAME.replace(/\./g, "\\.")}`)
+  );
+});
+
+test("treats a resolver query that never returns as not-visible, instead of hanging the whole flow", async () => {
+  const clock = fakeClock();
+  const hungResolver = {
+    // Never resolves; only the per-query timeout can move this along.
+    resolveTxt: () => new Promise<string[][]>(() => {}),
+  };
+
+  await assert.rejects(
+    () =>
+      waitForTxtPropagation(RECORD_NAME, EXPECTED_VALUE, {
+        publicResolver: hungResolver,
+        authoritativeResolverFactory: async () => ({ resolveTxt: async () => [] }),
+        initialDelayMs: 0,
+        pollIntervalMs: 10,
+        timeoutMs: 50,
+        queryTimeoutMs: 20,
+        now: clock.now,
+        sleep: clock.sleep,
+      }),
+    /timed out/
+  );
+});