acme: serve landmark-relative cert via rel="enhancement" URL

Re-introduce the landmark-relative cert over ACME using the new
"enhancement" link relation (ietf-plants-wg/merkle-tree-certs#257),
instead of the rel="alternate" form that was removed for stalling
clients.

The standalone /cert response advertises

  Link: <.../cert/{id}/landmark-relative/{number}>;rel="enhancement"

An enhancement is an optional, non-blocking substitute: the URL returns
HTTP 202 (Accepted) until the covering landmark is allocated, then the
signature-free landmark-relative cert. Clients retry the 202 honouring
Retry-After but never block deploying the standalone cert — so a
not-yet-available landmark can't stall issuance the way the old
alternate + 503 + Retry-After did (lego's go-retryablehttp treated that
503's Retry-After as a multi-hour blocking sleep).

The URL pins the number of the single landmark the entry is relative to
(ContainingIndex), making it an immutable resource: 202 until that
landmark is allocated, the same cert bytes forever after, and a
permanent 404 for any other number. Retry-After is derived from the
remaining time in the §6.3.2 landmark interval, so it reflects when the
cert is actually expected.

Adds landmark.Sequence.NextNumber and TimeUntilNextLandmark; re-wires the
acme.Config landmark fields; new tests acme/enhancement_test.go and
integration/landmark_enhancement_test.go; updates README/MTC/test-instance.

Author: mcpherrinm

MTC.md

@@ -322,15 +322,19 @@ In cactus:
 - `cert.BuildLandmarkRelativeCert` re-uses the existing standalone
   cert's TBS (so subject, validity, SPKI all match) and replaces
   only the signature value with a landmark MTCProof.
-- `cmd/cactus-cli cert landmark-relative` derives the landmark-relative
-  cert from a standalone cert plus the log's tiles, once a covering
-  landmark exists. The ACME API itself only serves standalone certs.
+- `acme.Server` advertises the landmark-relative cert as a
+  `rel="enhancement"` URL on the standalone cert response, served by
+  `handleCertLandmarkRelative` at `/cert/{id}/landmark-relative/{number}`
+  (see "Doing it over ACME" below).
+- `cmd/cactus-cli cert landmark-relative` derives the same cert from a
+  standalone cert plus the log's tiles, for use outside ACME.
 
 The relying-party side is exercised by
-`integration/TestCLICertLandmarkRelative`: it converts a standalone cert
-to landmark-relative form via `cactus-cli` and verifies it against the
-live log (signature-free, the inclusion proof reconstructs the log's
-subtree hash) without consulting any cosigner key.
+`integration/TestEnhancementURLSwitchover` (over ACME) and
+`integration/TestCLICertLandmarkRelative` (via cactus-cli): each obtains a
+landmark-relative cert and verifies it against the live log (signature-free,
+the inclusion proof reconstructs the log's subtree hash) without consulting
+any cosigner key.
 
 ## §7.2: Verifying a certificate
 
@@ -378,28 +382,33 @@ ACME is what the authenticating party (the cert holder) uses to
    `Accept: application/pem-certificate-chain-with-properties`. The
    server then includes a `CertificatePropertyList` alongside the
    PEM (cactus uses an adjacent `MTC PROPERTIES` PEM block; the
-   trust-anchor-ids draft hasn't pinned the wire format yet). For the
-   standalone certs the ACME API issues, the property list carries a
-   single `trust_anchor_id` — the **CA ID** (§8.1).
-
-   (The landmark-relative form, whose `trust_anchor_id` is the specific
-   landmark's ID `CA-ID.1.logNumber.L` per §8.2, is produced out-of-band
-   with `cactus-cli cert landmark-relative`, not over ACME. A relying
+   trust-anchor-ids draft hasn't pinned the wire format yet). The
+   property list carries a single `trust_anchor_id` — the **CA ID**
+   (§8.1) for a standalone cert, or the specific landmark's ID
+   `CA-ID.1.logNumber.L` (§8.2) for a landmark-relative cert. A relying
    party advertises a **landmark group** `CA-ID.2.logNumber.L` (§8.2.1)
    in its `trust_anchors` to accept the CA's standalone certs and all
-   active landmarks at once.)
+   active landmarks at once.
+3. **Enhancement URL.** The standalone cert response carries a
+   `Link: <…>; rel="enhancement"` header (trust-anchor-ids) pointing at
+   the landmark-relative variant, at
+   `/cert/{id}/landmark-relative/{number}`. The number pins the single
+   landmark the entry is relative to (`ContainingIndex`), so the URL is
+   an immutable resource: it returns `HTTP 202 (Accepted)` + `Retry-After`
+   until that landmark is allocated, then the cert. An *enhancement* is
+   an optional, non-blocking substitute — a client retries the 202 later
+   but must never let it hold up deploying the standalone cert.
+
+   This replaced an earlier `rel="alternate"` + `503 + Retry-After`
+   design. `alternate` is load-bearing: clients (e.g. lego, via
+   `go-retryablehttp`) fetch it eagerly during issuance and honour the
+   `Retry-After` on the 503, so a not-yet-available landmark stalled
+   issuance for the full interval. `enhancement` + 202 is non-blocking,
+   and pinning the landmark number keeps the URL stable.
 
 Cactus implements the above in `acme/` plus the property-list builder
 in `cert/properties.go`.
 
-> **Note.** Earlier revisions also exposed the landmark-relative cert
-> over ACME as a `rel="alternate"` URL (RFC 8555 §7.4.2) that returned
-> `503 + Retry-After` until a covering landmark existed. That was
-> removed: ACME clients (e.g. lego, via `go-retryablehttp`) follow the
-> alternate link immediately and honour the `Retry-After` on the 503,
-> stalling issuance for the full interval. The landmark-relative form is
-> now obtained from the log with `cactus-cli` instead.
-
 ## Cactus implementation map
 
 If you're reading the code, this is the order I'd recommend:

README.md

@@ -49,9 +49,10 @@ operate it, and where to look in the code.
   signatures.
 - Supports **landmark-relative certificates** (§6.3). Allocates
   landmarks per §6.3.2 and serves a `/landmarks` endpoint per §6.3.1.
-  The signature-free landmark-relative form is derived from the log
-  out-of-band with `cactus-cli cert landmark-relative` (not over the
-  ACME API).
+  The standalone cert advertises the signature-free landmark-relative
+  form as a `rel="enhancement"` URL (an optional, non-blocking substitute
+  that returns HTTP 202 until a covering landmark exists). The same form
+  is also derivable from the log with `cactus-cli cert landmark-relative`.
 - Acts as a **CA cosigner** using ML-DSA-44 (requires a Go 1.27+ build).
 - Optionally **runs as a cosigning mirror** for an external upstream
   log ([tlog-mirror], [tlog-cosignature]). In mirror mode cactus

acme/enhancement_test.go

@@ -0,0 +1,145 @@
+package acme
+
+import (
+	"context"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/go-jose/go-jose/v4"
+
+	"github.com/letsencrypt/cactus/ca"
+	"github.com/letsencrypt/cactus/cert"
+	"github.com/letsencrypt/cactus/landmark"
+	cactuslog "github.com/letsencrypt/cactus/log"
+	"github.com/letsencrypt/cactus/signer"
+	"github.com/letsencrypt/cactus/storage"
+)
+
+// TestEnhancementURLPending pins the draft §9 "enhancement" behaviour
+// before a covering landmark exists: the standalone cert advertises the
+// landmark-relative cert via rel="enhancement" at a URL pinned to the
+// landmark number it will be relative to, and that URL returns HTTP 202
+// (Accepted) + Retry-After — non-blocking, never the rel="alternate" +
+// 503 that stalled clients.
+func TestEnhancementURLPending(t *testing.T) {
+	dir := t.TempDir()
+	fs, _ := storage.New(dir)
+	seed := make([]byte, signer.SeedSize)
+	for i := range seed {
+		seed[i] = 0xDE
+	}
+	sgn, _ := signer.FromSeed(signer.AlgMLDSA44, seed)
+	logID := cert.TrustAnchorID("32473.1")
+	l, _ := cactuslog.New(context.Background(), cactuslog.Config{
+		LogID: logID, CosignerID: logID,
+		Signer: sgn, FS: fs, FlushPeriod: 25 * time.Millisecond,
+	})
+	defer l.Stop()
+	issuer, _ := ca.New(l, "32473.1", 1)
+
+	// TimeBetweenLandmarks is long: no landmark is allocated during the
+	// test, so the enhancement URL stays in the pending (202) state.
+	seq, err := landmark.New(landmark.Config{
+		CAID: logID, LogNumber: 1,
+		TimeBetweenLandmarks: time.Hour, MaxCertLifetime: time.Hour,
+	}, fs, time.Date(2026, 5, 1, 0, 0, 0, 0, time.UTC))
+	if err != nil {
+		t.Fatal(err)
+	}
+	srv, _ := New(Config{
+		Issuer: issuer, ChallengeMode: ChallengeAutoPass,
+		Landmarks: seq, SubtreeProof: l.SubtreeProof,
+		LogID: logID, CAID: logID, LogNumber: 1,
+	})
+	hsrv := httptest.NewServer(srv.Handler())
+	defer hsrv.Close()
+	srv.SetExternalURL(hsrv.URL)
+
+	// Issue one cert end-to-end so we have a real cert URL.
+	acctKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	acctJWK := &jose.JSONWebKey{Key: acctKey.Public(), Algorithm: "ES256"}
+	nonce := nonceFor(t, hsrv.URL)
+	jws := jwsSign(t, acctKey, acctJWK, "", nonce, hsrv.URL+"/new-account",
+		mustMarshal(NewAccountReq{TermsOfServiceAgreed: true}))
+	resp, _ := post(t, hsrv.URL, "/new-account", jws)
+	kid := resp.Header.Get("Location")
+	nonce = resp.Header.Get("Replay-Nonce")
+	jws = jwsSign(t, acctKey, nil, kid, nonce, hsrv.URL+"/new-order",
+		mustMarshal(NewOrderReq{Identifiers: []Identifier{{Type: "dns", Value: "enh.test"}}}))
+	resp, body := post(t, hsrv.URL, "/new-order", jws)
+	var ord OrderResp
+	json.Unmarshal(body, &ord)
+	csrKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	csr, _ := x509.CreateCertificateRequest(rand.Reader, &x509.CertificateRequest{
+		Subject: pkix.Name{CommonName: "enh.test"}, DNSNames: []string{"enh.test"},
+	}, csrKey)
+	nonce = resp.Header.Get("Replay-Nonce")
+	jws = jwsSign(t, acctKey, nil, kid, nonce, ord.Finalize,
+		mustMarshal(FinalizeReq{CSR: base64.RawURLEncoding.EncodeToString(csr)}))
+	resp, body = post(t, hsrv.URL, strings.TrimPrefix(ord.Finalize, hsrv.URL), jws)
+	var ord2 OrderResp
+	json.Unmarshal(body, &ord2)
+	if ord2.Certificate == "" {
+		t.Fatal("missing cert URL")
+	}
+
+	// The standalone cert response advertises the landmark-relative cert
+	// as an enhancement, pinned to a landmark number.
+	certResp, _ := postAsGet(t, hsrv.URL, ord2.Certificate, acctKey, kid, "")
+	link := certResp.Header.Get("Link")
+	if !strings.Contains(link, `rel="enhancement"`) {
+		t.Errorf("cert Link missing rel=enhancement: %q", link)
+	}
+	enh := linkURL(link)
+	if !strings.Contains(enh, "/landmark-relative/") {
+		t.Fatalf("enhancement URL not a landmark-relative URL: %q", enh)
+	}
+	// Index 0's covering landmark is the next one to be allocated (1).
+	if !strings.HasSuffix(enh, "/landmark-relative/1") {
+		t.Errorf("enhancement URL = %q, want it pinned to landmark 1", enh)
+	}
+
+	// Before the landmark is allocated, the enhancement URL returns 202 +
+	// Retry-After.
+	r2, _ := postAsGet(t, hsrv.URL, enh, acctKey, kid, "")
+	if r2.StatusCode != http.StatusAccepted {
+		t.Errorf("status = %d, want 202", r2.StatusCode)
+	}
+	ra := r2.Header.Get("Retry-After")
+	if ra == "" {
+		t.Fatal("missing Retry-After header")
+	}
+	if _, err := strconv.Atoi(ra); err != nil {
+		if _, err := http.ParseTime(ra); err != nil {
+			t.Errorf("Retry-After %q is neither integer nor HTTP-date", ra)
+		}
+	}
+
+	// A landmark number this cert is not relative to is a permanent 404.
+	wrong := strings.TrimSuffix(enh, "/1") + "/2"
+	r3, _ := postAsGet(t, hsrv.URL, wrong, acctKey, kid, "")
+	if r3.StatusCode != http.StatusNotFound {
+		t.Errorf("wrong-landmark status = %d, want 404", r3.StatusCode)
+	}
+}
+
+// linkURL returns the URL inside a `<url>;rel="..."` Link header value.
+func linkURL(link string) string {
+	start := strings.Index(link, "<")
+	end := strings.Index(link, ">")
+	if start < 0 || end < 0 || end < start {
+		return ""
+	}
+	return link[start+1 : end]
+}