acme: drop landmark-relative alternate URL (fixes lego issuance hang)

The /cert/{id}/alternate URL served the §9 "not yet available" stub
(503 + Retry-After: 3600) until a covering landmark existed — the normal
case immediately after issuance, since landmarks lag. ACME clients follow
the rel="alternate" Link on the finalize/cert responses right away;
lego's go-retryablehttp transport honours Retry-After on a 503 and sleeps
its full value per retry (RetryMax 5 × 3600s) against a context.Background
request with no client timeout, so issuance hung for hours. It was
intermittent only when a covering landmark happened to already exist.

Remove the alternate URL, its 503 stub, the rel="alternate" Link headers,
and the alternate-only acme.Config fields (Landmarks, SubtreeProof,
LogNumber). The standalone cert is fully usable on its own; the
landmark-relative form is now produced out-of-band from the log with
`cactus-cli cert landmark-relative`.

Drop the alternate-URL tests (RP fast-path verification stays covered by
integration TestCLICertLandmarkRelative) and update the README/MTC/
test-instance docs.

Author: mcpherrinm

MTC.md

@@ -321,14 +321,15 @@ 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.
-- `acme.Server`'s alternate URL `(/cert/<id>/alternate)` returns a
-  `503 + Retry-After` until a covering landmark exists, then
-  returns the real landmark-relative cert.
+- `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.
 
 The relying-party side is exercised by
-`integration/TestRelyingPartyFastPath`: the test simulates an RP
-that has only `/landmarks` and the tile-served subtree hashes, then
-verifies a landmark-relative cert without consulting any cosigner key.
+`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.
 
 ## §7.2: Verifying a certificate
 
@@ -376,23 +377,27 @@ 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). The
-   property list carries a single:
-   - `trust_anchor_id` — the **CA ID** for standalone certs (§8.1), or
-     the specific landmark's ID `CA-ID.1.logNumber.L` for
-     landmark-relative certs (§8.2).
-
-   A relying party advertises a **landmark group**
-   `CA-ID.2.logNumber.L` (§8.2.1) in its `trust_anchors`, signalling
-   support for the CA's standalone certs and all active landmarks at
-   once.
-3. **Alternate URL.** Per RFC 8555 §7.4.2, the `Link: <...>;
-   rel="alternate"` header on the `/finalize` response points at
-   the landmark-relative variant of the cert. Until a landmark
-   covers the entry, that URL returns `503 + Retry-After`.
-
-Cactus implements all of the above in `acme/` plus the
-property-list builder in `cert/properties.go`.
+   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
+   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.)
+
+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
 

README.md

@@ -47,11 +47,11 @@ operate it, and where to look in the code.
   `signatureAlgorithm` is `id-alg-mtcProof` and whose `signatureValue`
   body is an `MTCProof` blob carrying an inclusion proof + cosigner
   signatures.
-- Issues **landmark-relative certificates** (§6.3) alongside the
-  standalone ones. Allocates landmarks per §6.3.2, serves a
-  `/landmarks` endpoint per §6.3.1, and switches the §9 alternate URL
-  from a `503` stub to a real signature-less cert once a covering
-  landmark exists.
+- 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).
 - 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/alternate_test.go

@@ -21,9 +21,7 @@ import (
 
 	"github.com/letsencrypt/cactus/ca"
 	"github.com/letsencrypt/cactus/cert"
-	"github.com/letsencrypt/cactus/landmark"
 	cactusmetrics "github.com/letsencrypt/cactus/metrics"
-	"github.com/letsencrypt/cactus/tlogx"
 )
 
 // ChallengeMode controls how challenges are validated.
@@ -52,31 +50,15 @@ type Config struct {
 	// "invalid" on failure. Optional.
 	OrdersByStatus cactusmetrics.CounterVec
 
-	// Landmarks, if non-nil, enables the alternate-URL
-	// switchover: GET /cert/{id}/alternate returns a real
-	// landmark-relative cert once a covering landmark exists.
-	// Otherwise the alternate URL keeps the §9-permitted 503 stub.
-	Landmarks *landmark.Sequence
-
-	// SubtreeProof, if set, is used to compute inclusion proofs for
-	// landmark-relative cert assembly. Must be set whenever
-	// Landmarks is. Typically `(*log.Log).SubtreeProof`.
-	SubtreeProof func(start, end, index uint64) (tlogx.Hash, []tlogx.Hash, error)
-
-	// LogID is the issuance log's trust anchor ID (§5.2). Required
-	// only when Landmarks is set (and for the standalone-cert
-	// `trust_anchor_id` property emitted in
-	// application/pem-certificate-chain-with-properties).
+	// LogID is the issuance log's trust anchor ID (§5.2). Used as the
+	// fallback for the standalone-cert `trust_anchor_id` property
+	// emitted in application/pem-certificate-chain-with-properties when
+	// CAID is unset.
 	LogID cert.TrustAnchorID
 
-	// CAID is the CA's CA ID (§5.1). Required whenever Landmarks is set;
-	// landmark trust anchor IDs are derived from it and LogNumber
-	// (CA-ID.1.logNumber.L, §6.3.1).
+	// CAID is the CA's CA ID (§5.1). Emitted as the standalone cert's
+	// `trust_anchor_id` property (draft-04 §8.1).
 	CAID cert.TrustAnchorID
-
-	// LogNumber is the issuance log's number (§5.2). Required whenever
-	// Landmarks is set.
-	LogNumber uint16
 }
 
 // Server is the ACME HTTP server.
@@ -130,7 +112,6 @@ func (s *Server) Handler() http.Handler {
 	mux.HandleFunc("POST /order/{id}", s.handleOrder)
 	mux.HandleFunc("POST /finalize/{id}", s.handleFinalize)
 	mux.HandleFunc("POST /cert/{id}", s.handleCert)
-	mux.HandleFunc("POST /cert/{id}/alternate", s.handleCertAlternate)
 	return mux
 }
 
@@ -975,7 +956,6 @@ func (s *Server) handleFinalize(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Location", loc)
 	s.issueNonce(w)
 	w.Header().Set("Content-Type", "application/json")
-	w.Header().Set("Link", `<`+s.urlFor("/cert/"+certID+"/alternate")+`>;rel="alternate"`)
 	_ = json.NewEncoder(w).Encode(s.orderJSON(o))
 }
 
@@ -1005,7 +985,6 @@ func (s *Server) handleCert(w http.ResponseWriter, r *http.Request) {
 	}
 	s.issueNonce(w)
 	accept := r.Header.Get("Accept")
-	w.Header().Set("Link", `<`+s.urlFor("/cert/"+id+"/alternate")+`>;rel="alternate"`)
 	if strings.Contains(accept, "application/pem-certificate-chain-with-properties") {
 		w.Header().Set("Content-Type", "application/pem-certificate-chain-with-properties")
 		// Standalone cert: the trust_anchor_id property naming the CA
@@ -1037,126 +1016,6 @@ func (s *Server) handleCert(w http.ResponseWriter, r *http.Request) {
 	pem.Encode(w, &pem.Block{Type: "CERTIFICATE", Bytes: der})
 }
 
-// handleCertAlternate returns the landmark-relative cert for
-// the given cert id, falling back to 503 + Retry-After (the
-// §9-permitted stub) when a covering landmark hasn't been allocated yet
-// or when landmark mode is disabled.
-func (s *Server) handleCertAlternate(w http.ResponseWriter, r *http.Request) {
-	id := r.PathValue("id")
-	parsed, acct, err := s.readJWS(r, true)
-	if err != nil {
-		s.writeJWSError(w, err)
-		return
-	}
-	if !EmptyPayloadOK(parsed.Payload) {
-		s.problem(w, http.StatusBadRequest, "urn:ietf:params:acme:error:malformed",
-			"cert download must be POST-as-GET (empty payload)")
-		return
-	}
-	s.state.mu.Lock()
-	standalone, ok := s.certs[id]
-	s.state.mu.Unlock()
-	if !ok {
-		s.problem(w, http.StatusNotFound, "urn:ietf:params:acme:error:malformed", "no certificate")
-		return
-	}
-	if !s.certBelongsToAccount(id, acct.ID) {
-		s.problem(w, http.StatusUnauthorized, "urn:ietf:params:acme:error:unauthorized",
-			"certificate does not belong to this account")
-		return
-	}
-	s.issueNonce(w)
-
-	// Pull the serial out of the standalone cert and split off the log
-	// index: draft-04 §6.1, serial = (log_number << 48) | index.
-	tbs, _, _, err := cert.SplitCertificate(standalone)
-	if err != nil {
-		http.Error(w, "split cert: "+err.Error(), http.StatusInternalServerError)
-		return
-	}
-	_, serial, err := cert.RebuildLogEntryFromTBS(tbs, nil)
-	if err != nil {
-		http.Error(w, "decode TBS: "+err.Error(), http.StatusInternalServerError)
-		return
-	}
-	_, index, err := cert.SplitSerial(serial)
-	if err != nil {
-		http.Error(w, "decode serial: "+err.Error(), http.StatusInternalServerError)
-		return
-	}
-
-	if s.cfg.Landmarks == nil || s.cfg.SubtreeProof == nil {
-		s.serveAltStub(w)
-		return
-	}
-
-	lm, ok := s.cfg.Landmarks.ContainingIndex(index)
-	if !ok {
-		s.serveAltStub(w)
-		return
-	}
-
-	// Pick the §4.5 covering subtree of [prev_treeSize, lm.TreeSize)
-	// that contains the entry index.
-	subtrees := s.cfg.Landmarks.LandmarkSubtrees(lm)
-	var chosen tlogx.Subtree
-	for _, st := range subtrees {
-		if index >= st.Start && index < st.End {
-			chosen = st
-			break
-		}
-	}
-	if chosen.End == 0 {
-		// Inconsistent state: ContainingIndex said yes but no covering
-		// subtree contains the index. Treat as not-yet-available.
-		s.serveAltStub(w)
-		return
-	}
-
-	subtreeHash, proof, err := s.cfg.SubtreeProof(chosen.Start, chosen.End, index)
-	if err != nil {
-		http.Error(w, "subtree proof: "+err.Error(), http.StatusInternalServerError)
-		return
-	}
-
-	mtcSubtree := cert.MTCSubtree{
-		LogID: s.cfg.LogID,
-		Start: chosen.Start, End: chosen.End,
-		Hash: subtreeHash,
-	}
-	der, err := cert.BuildLandmarkRelativeCert(standalone, s.cfg.LogID, mtcSubtree, proof)
-	if err != nil {
-		http.Error(w, "build landmark cert: "+err.Error(), http.StatusInternalServerError)
-		return
-	}
-
-	accept := r.Header.Get("Accept")
-	if strings.Contains(accept, "application/pem-certificate-chain-with-properties") {
-		w.Header().Set("Content-Type", "application/pem-certificate-chain-with-properties")
-		// draft-04 §8.2: a landmark-relative certificate's trust anchor
-		// ID is the individual landmark ID (CA-ID.1.logNumber.L).
-		// Relying parties advertise a landmark group (§8.2.1) instead.
-		props := []cert.CertificateProperty{
-			{Type: cert.PropertyTrustAnchorID, TrustAnchorID: lm.TrustAnchorID(s.cfg.CAID, s.cfg.LogNumber)},
-		}
-		pl, err := cert.BuildPropertyList(props)
-		if err != nil {
-			http.Error(w, "build properties: "+err.Error(), http.StatusInternalServerError)
-			return
-		}
-		w.Write(cert.EncodePEMWithProperties(der, pl))
-		return
-	}
-	w.Header().Set("Content-Type", "application/pem-certificate-chain")
-	pem.Encode(w, &pem.Block{Type: "CERTIFICATE", Bytes: der})
-}
-
-// serveAltStub is the §9-permitted "not yet available" response.
-func (s *Server) serveAltStub(w http.ResponseWriter) {
-	w.Header().Set("Retry-After", "3600")
-	http.Error(w, "landmark-relative certificate not yet available", http.StatusServiceUnavailable)
-}
-
 // certBelongsToAccount returns true if the cert with the given id is
 // the certificate produced for an order whose AccountID matches.
 func (s *Server) certBelongsToAccount(certID, accountID string) bool {

acme/handler.go

@@ -265,13 +265,6 @@ func TestEndToEndIssuance(t *testing.T) {
 		t.Errorf("suspiciously short cert: %d bytes", len(block.Bytes))
 	}
 
-	// 8. Alternate URL returns 503 + Retry-After.
-	altURL := strings.TrimSuffix(ord2.Certificate, "/cert") + "/cert/" + lastSegment(ord2.Certificate) + "/alternate"
-	resp, _ = postAsGet(t, base, altURL, acctKey, kid, "")
-	if resp.StatusCode != http.StatusServiceUnavailable {
-		t.Logf("alternate URL: status=%d (expected 503)", resp.StatusCode)
-	}
-
 	_ = orderURL
 	_ = ord
 }