github.com/mholt/acmez/v3 v3.1.2: acmez.Client

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify acmez.Client in pkg:golang/github.com/mholt/acmez/v3@v3.1.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/mholt/acmez/v3@v3.1.2
Demonstrate these symbols/APIs:
  - acmez.Client

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:f580bd3f309665626e8145f84b3c77f07c442155d706515cae625770bd0d3560","contract":["acmez.Client embeds *acme.Client and configures ChallengeSolvers map","acmez.Client.ObtainCertificate executes challenge solving lifecycle (Present and CleanUp) via registered acmez.Solver","acmez.Client.ObtainCertificate finalizes order and retrieves PEM certificate chains from ACME server","acmez.Client.ObtainCertificate returns error when no solver is registered for an active challenge type","acmez.Client.ObtainCertificateForSANs generates CSR and completes certificate issuance for specified SANs"],"goal":"verify acmez.Client in pkg:golang/github.com/mholt/acmez/v3@v3.1.2","kind":"HOW","packages":["pkg:golang/github.com/mholt/acmez/v3@v3.1.2"],"schemaVersion":1,"symbols":["acmez.Client"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/mholt/acmez/v3@v3.1.2"],"schemaVersion":1,"subject":"pkg:golang/github.com/mholt/acmez/v3@v3.1.2","symbols":["acmez.Client"],"verifierAdapter":"golang@1"}

module sample-acmez-client

go 1.24.0

require github.com/mholt/acmez/v3 v3.1.2

require (
	golang.org/x/crypto v0.48.0 // indirect
	golang.org/x/net v0.50.0 // indirect
	golang.org/x/text v0.34.0 // indirect
)

code.pfad.fr/check v1.1.0 h1:GWvjdzhSEgHvEHe2uJujDcpmZoySKuHQNrZMfzfO0bE=
code.pfad.fr/check v1.1.0/go.mod h1:NiUH13DtYsb7xp5wll0U4SXx7KhXQVCtRgdC96IPfoM=
github.com/go-jose/go-jose/v4 v4.1.3 h1:CVLmWDhDVRa6Mi/IgCgaopNosCaHz7zrMeF9MlZRkrs=
github.com/go-jose/go-jose/v4 v4.1.3/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
github.com/letsencrypt/challtestsrv v1.4.2 h1:0ON3ldMhZyWlfVNYYpFuWRTmZNnyfiL9Hh5YzC3JVwU=
github.com/letsencrypt/challtestsrv v1.4.2/go.mod h1:GhqMqcSoeGpYd5zX5TgwA6er/1MbWzx/o7yuuVya+Wk=
github.com/letsencrypt/pebble/v2 v2.10.0 h1:Wq6gYXlsY6ubqI3hhxsTzdyotvfdjFBxuwYqCLCnj/U=
github.com/letsencrypt/pebble/v2 v2.10.0/go.mod h1:Sk8cmUIPcIdv2nINo+9PB4L+ZBhzY+F9A1a/h/xmWiQ=
github.com/mholt/acmez/v3 v3.1.2 h1:auob8J/0FhmdClQicvJvuDavgd5ezwLBfKuYmynhYzc=
github.com/mholt/acmez/v3 v3.1.2/go.mod h1:L1wOU06KKvq7tswuMDwKdcHeKpFFgkppZy/y0DFxagQ=
github.com/mholt/acmez/v3 v3.1.6 h1:eGVQNObP0pBN4sxqrXeg7MYqTOWyoiYpQqITVWlrevk=
github.com/mholt/acmez/v3 v3.1.6/go.mod h1:5nTPosTGosLxF3+LU4ygbgMRFDhbAVpqMI4+a4aHLBY=
github.com/miekg/dns v1.1.72 h1:vhmr+TF2A3tuoGNkLDFK9zi36F2LS+hKTRW0Uf8kbzI=
github.com/miekg/dns v1.1.72/go.mod h1:+EuEPhdHOsfk6Wk5TT2CzssZdqkmFhf8r+aVyDEToIs=
golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
golang.org/x/mod v0.32.0 h1:9F4d3PHLljb6x//jOyokMv3eX+YDeepZSEo3mFJy93c=
golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
golang.org/x/tools v0.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc=
golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=

package main

import (
	"context"
	"fmt"

	"github.com/mholt/acmez/v3"
	"github.com/mholt/acmez/v3/acme"
)

// ExampleSolver demonstrates implementing the acmez.Solver interface for HTTP-01 challenges.
type ExampleSolver struct{}

func (s *ExampleSolver) Present(ctx context.Context, chal acme.Challenge) error {
	fmt.Printf("Presenting challenge token for %s\n", chal.Type)
	return nil
}

func (s *ExampleSolver) CleanUp(ctx context.Context, chal acme.Challenge) error {
	fmt.Printf("Cleaning up challenge token for %s\n", chal.Type)
	return nil
}

func main() {
	acmeClient := &acme.Client{
		Directory: "https://example.com/acme/directory",
	}

	client := acmez.Client{
		Client: acmeClient,
		ChallengeSolvers: map[string]acmez.Solver{
			acme.ChallengeTypeHTTP01: &ExampleSolver{},
		},
	}

	fmt.Printf("ACME Client configured with directory: %s\n", client.Client.Directory)
	fmt.Printf("Registered %d challenge solver(s)\n", len(client.ChallengeSolvers))
}

{
  "schemaVersion": 1,
  "goal": "verify acmez.Client in pkg:golang/github.com/mholt/acmez/v3@v3.1.2",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/mholt/acmez/v3@v3.1.2"
  ],
  "symbols": [
    "acmez.Client"
  ]
}

package main

import (
	"context"
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
	"crypto/x509"
	"crypto/x509/pkix"
	"encoding/pem"
	"fmt"
	"math/big"
	"net/http"
	"net/http/httptest"
	"os"
	"strings"
	"sync"
	"sync/atomic"
	"time"

	"github.com/mholt/acmez/v3"
	"github.com/mholt/acmez/v3/acme"
)

type mockSolver struct {
	mu        sync.Mutex
	presented []acme.Challenge
	cleanedUp []acme.Challenge
}

func (s *mockSolver) Present(ctx context.Context, chal acme.Challenge) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	s.presented = append(s.presented, chal)
	return nil
}

func (s *mockSolver) CleanUp(ctx context.Context, chal acme.Challenge) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	s.cleanedUp = append(s.cleanedUp, chal)
	return nil
}

func main() {
	privKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: key generation: %v\n", err)
		os.Exit(1)
	}

	certTemplate := x509.Certificate{
		SerialNumber: big.NewInt(1001),
		Subject:      pkix.Name{CommonName: "example.com"},
		DNSNames:     []string{"example.com"},
		NotBefore:    time.Now().Add(-1 * time.Hour),
		NotAfter:     time.Now().Add(24 * time.Hour),
	}
	certDER, err := x509.CreateCertificate(rand.Reader, &certTemplate, &certTemplate, privKey.Public(), privKey)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: mock cert creation: %v\n", err)
		os.Exit(1)
	}
	certPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: certDER})

	var nonceCounter int64
	var orderCounter int64
	var chalInitiated int32
	var serverURL string

	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		count := atomic.AddInt64(&nonceCounter, 1)
		w.Header().Set("Replay-Nonce", fmt.Sprintf("nonce-%d", count))

		path := r.URL.Path
		switch {
		case path == "/dir":
			w.Header().Set("Content-Type", "application/json")
			fmt.Fprintf(w, `{"newNonce":"%s/new-nonce","newAccount":"%s/new-account","newOrder":"%s/new-order"}`, serverURL, serverURL, serverURL)
		case path == "/new-nonce":
			w.WriteHeader(http.StatusOK)
		case path == "/new-account":
			w.Header().Set("Content-Type", "application/json")
			w.Header().Set("Location", serverURL+"/acct/100")
			w.WriteHeader(http.StatusCreated)
			fmt.Fprintf(w, `{"status":"valid","contact":["mailto:admin@example.com"]}`)
		case path == "/new-order":
			ordID := atomic.AddInt64(&orderCounter, 1)
			atomic.StoreInt32(&chalInitiated, 0)
			w.Header().Set("Content-Type", "application/json")
			w.Header().Set("Location", fmt.Sprintf("%s/order/%d", serverURL, ordID))
			w.WriteHeader(http.StatusCreated)
			fmt.Fprintf(w, `{"status":"pending","authorizations":["%s/authz/%d"],"finalize":"%s/finalize/%d"}`, serverURL, ordID, serverURL, ordID)
		case strings.HasPrefix(path, "/authz/"):
			w.Header().Set("Content-Type", "application/json")
			w.WriteHeader(http.StatusOK)
			status := "pending"
			if atomic.LoadInt32(&chalInitiated) > 0 {
				status = "valid"
			}
			fmt.Fprintf(w, `{"status":"%s","identifier":{"type":"dns","value":"example.com"},"challenges":[{"type":"http-01","url":"%s/chal/1","token":"test-token-123","status":"%s"}]}`, status, serverURL, status)
		case strings.HasPrefix(path, "/chal/"):
			atomic.StoreInt32(&chalInitiated, 1)
			w.Header().Set("Content-Type", "application/json")
			w.WriteHeader(http.StatusOK)
			fmt.Fprintf(w, `{"type":"http-01","url":"%s/chal/1","token":"test-token-123","status":"valid"}`, serverURL)
		case strings.HasPrefix(path, "/finalize/"):
			w.Header().Set("Content-Type", "application/json")
			w.WriteHeader(http.StatusOK)
			fmt.Fprintf(w, `{"status":"valid","certificate":"%s/cert/1"}`, serverURL)
		case strings.HasPrefix(path, "/order/"):
			w.Header().Set("Content-Type", "application/json")
			w.WriteHeader(http.StatusOK)
			fmt.Fprintf(w, `{"status":"valid","certificate":"%s/cert/1"}`, serverURL)
		case strings.HasPrefix(path, "/cert/"):
			w.Header().Set("Content-Type", "application/pem-certificate-chain")
			w.WriteHeader(http.StatusOK)
			w.Write(certPEM)
		default:
			http.NotFound(w, r)
		}
	}))
	defer ts.Close()
	serverURL = ts.URL

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	acmeClient := &acme.Client{
		Directory:  serverURL + "/dir",
		HTTPClient: ts.Client(),
	}

	registeredAcct, err := acmeClient.NewAccount(ctx, acme.Account{
		Contact:              []string{"mailto:admin@example.com"},
		TermsOfServiceAgreed: true,
		PrivateKey:           privKey,
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: NewAccount: %v\n", err)
		os.Exit(1)
	}

	// Assertion 1: acmez.Client embeds *acme.Client and configures ChallengeSolvers map
	solver := &mockSolver{}
	client := acmez.Client{
		Client: acmeClient,
		ChallengeSolvers: map[string]acmez.Solver{
			acme.ChallengeTypeHTTP01: solver,
		},
	}
	if client.Client == nil || client.Client.Directory != serverURL+"/dir" {
		fmt.Fprintf(os.Stderr, "FAIL: acmez.Client embedded acme.Client mismatch\n")
		os.Exit(1)
	}
	if len(client.ChallengeSolvers) != 1 || client.ChallengeSolvers[acme.ChallengeTypeHTTP01] == nil {
		fmt.Fprintf(os.Stderr, "FAIL: acmez.Client ChallengeSolvers not configured\n")
		os.Exit(1)
	}

	// Assertion 2: acmez.Client.ObtainCertificate executes challenge solving lifecycle (Present and CleanUp) via registered acmez.Solver
	csr, err := acmez.NewCSR(privKey, []string{"example.com"})
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: NewCSR: %v\n", err)
		os.Exit(1)
	}
	orderParams, err := acmez.OrderParametersFromCSR(registeredAcct, csr)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: OrderParametersFromCSR: %v\n", err)
		os.Exit(1)
	}

	certs, err := client.ObtainCertificate(ctx, orderParams)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: ObtainCertificate: %v\n", err)
		os.Exit(1)
	}
	solver.mu.Lock()
	if len(solver.presented) != 1 || solver.presented[0].Type != acme.ChallengeTypeHTTP01 {
		fmt.Fprintf(os.Stderr, "FAIL: solver.Present was not called with http-01 challenge\n")
		os.Exit(1)
	}
	if len(solver.cleanedUp) != 1 || solver.cleanedUp[0].Type != acme.ChallengeTypeHTTP01 {
		fmt.Fprintf(os.Stderr, "FAIL: solver.CleanUp was not called with http-01 challenge\n")
		os.Exit(1)
	}
	solver.mu.Unlock()

	// Assertion 3: acmez.Client.ObtainCertificate finalizes order and retrieves PEM certificate chains from ACME server
	if len(certs) == 0 {
		fmt.Fprintf(os.Stderr, "FAIL: expected non-empty certificate chain\n")
		os.Exit(1)
	}
	if certs[0].URL != serverURL+"/cert/1" {
		fmt.Fprintf(os.Stderr, "FAIL: certificate URL mismatch: %s\n", certs[0].URL)
		os.Exit(1)
	}
	if len(certs[0].ChainPEM) == 0 {
		fmt.Fprintf(os.Stderr, "FAIL: certificate ChainPEM is empty\n")
		os.Exit(1)
	}

	// Assertion 4: acmez.Client.ObtainCertificate returns error when no solver is registered for an active challenge type
	clientWithoutSolvers := acmez.Client{
		Client:           acmeClient,
		ChallengeSolvers: map[string]acmez.Solver{},
	}
	_, err = clientWithoutSolvers.ObtainCertificate(ctx, orderParams)
	if err == nil {
		fmt.Fprintf(os.Stderr, "FAIL: ObtainCertificate should fail when no challenge solver is registered\n")
		os.Exit(1)
	}

	// Assertion 5: acmez.Client.ObtainCertificateForSANs generates CSR and completes certificate issuance for specified SANs
	sansSolver := &mockSolver{}
	clientForSANs := acmez.Client{
		Client: acmeClient,
		ChallengeSolvers: map[string]acmez.Solver{
			acme.ChallengeTypeHTTP01: sansSolver,
		},
	}
	sanCerts, err := clientForSANs.ObtainCertificateForSANs(ctx, registeredAcct, privKey, []string{"example.com"})
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: ObtainCertificateForSANs: %v\n", err)
		os.Exit(1)
	}
	if len(sanCerts) == 0 || len(sanCerts[0].ChainPEM) == 0 {
		fmt.Fprintf(os.Stderr, "FAIL: ObtainCertificateForSANs returned empty certificate chain\n")
		os.Exit(1)
	}
	sansSolver.mu.Lock()
	if len(sansSolver.presented) == 0 {
		fmt.Fprintf(os.Stderr, "FAIL: sansSolver.Present was not called\n")
		os.Exit(1)
	}
	sansSolver.mu.Unlock()

	fmt.Println("PASS: acmez.Client contract passed")
}